Upgrading to 0.6
Most 0.5 apps run on 0.6 as they are. Everything new (teams, installable and desktop apps, the UI kit, webhooks, encrypted fields) is opt-in. This page lists what changed for existing apps and what, if anything, to do about it. The first step is always:
pip install -U pyweb-stack
pyweb upgrade --check app.pyweb # lists what to change, with file and line
pyweb upgrade --fix app.pyweb # applies the safe rewrites
pyweb check app.pyweb
pytest#From 0.6.2 to 0.6.3
0.6.3 closes security gaps, and three of the fixes can change how an existing app behaves. pyweb upgrade --check points at each one.
pyweb serveneeds a secret. It refuses to start withoutPYWEB_AUTH_SECRET(python -c "import secrets; print(secrets.token_hex(32))"makes one); setPYWEB_ENV=developmentto run a local server without one. Guarded server functions are refused when there's no secret instead of running unchecked. Sessions made with the old derived development key end once.- Postgres tenant tables get a new row-level security policy (
pyweb_tenant_v2) that shows no rows to a connection that never set the organization. Apps that create tables get it on start; with migrations, runpyweb db diffandpyweb db upgrade. - Forms carry a signed list of the fields they rendered. A page rendered by 0.6.2 and submitted after the upgrade gets "reload the page" once. A field your server function fills in without an input on the form must now be set in the function.
- An option in
@app.page(...)that isn't written as a value (login=NEEDS_LOGIN) is a compile error; write the value itself.
Everything new (routes, cache=, translations, <ErrorBoundary>, Stepper, <Image>) is opt-in. Update the VS Code extension to 0.6.3 for rename, find references and quick fixes.
#One migration, for apps with accounts
0.6 lists each signed-in device on /account, so people can sign one out. Apps that call app.use_auth() need the new auth_sessions table:
pyweb db upgrade # apply any migrations still pending
pyweb db diff --name auth_sessions
pyweb db upgradeUntil it exists, signing in works as before and the device list stays empty. pyweb upgrade --check reminds you while it's missing.
#Pages and markup
- Boolean attributes follow truthiness on the server too.
checked={row["done"]}with a database's0used to renderchecked="0", which browsers treat as checked. Now0,NoneandFalseleave the attribute out, as the browser already did. A literal string (disabled="") still renders as written. - Trusted Types. The default Content-Security-Policy now tells the browser to refuse plain strings in
innerHTML,insertAdjacentHTMLand similar places. PyWeb's own code is unaffected. If a script of your own instatic/writes HTML from a string, settextContent, build the elements, or addPYWEB_CSPwith your own policy. Pages that use npm packages don't get this rule. See Security. pyweb.platformis real.platform.desktop,platform.pwaandplatform.installednow answer per request.platform.mobileandplatform.edgewere placeholders and are always False;pyweb upgradepoints at them.- Form limits. A form post with more than 1,000 fields or 100 files gets a 400 instead of being parsed.
#Looks
- The sign-in, account, organization and admin pages use the UI kit and your app's theme.
App(theme=Theme(accent="#0f766e"))restyles them with the rest of the app. A stylesheet that targeted their 0.5 classes (.pw-primary,.pw-notice,--pw-ink, ...) no longer matches;pyweb upgrade --checknames those rules and the kit classes that replace them. - New templates use the kit. An app made from a 0.5 template keeps its own
static/app.cssand looks as it did. To see the new look, make a fresh app (pyweb new demo --template saas) and compare, or move pages ontofrom pyweb.ui import ...components one at a time. See UI kit and motion.
#Security and secrets
PYWEB_DATA_KEYis a new secret, used only if you addField(encrypted=True). Keep it apart fromPYWEB_AUTH_SECRET;pyweb check --productionasks for it when an encrypted field exists.pyweb checknow fails on keys written into the app (known formats such assk_live_...andghp_...) and warns about random-looking values in variables named like secrets. Move them to environment variables.- CSP reports arrive at
/__pyweb/csp-reportand are logged aspyweb.cspwarnings. A steady trickle is usually browser extensions.
#Python
0.6 supports Python 3.10 to 3.15, including free-threaded 3.15t, where one pyweb serve process uses every core. Models now work on 3.14 and later (0.5's broke there), so upgrade PyWeb before upgrading Python.
#Editors and assistants
Update the VS Code extension to 0.6 for the new completions and warnings (org_role=, rate=, webhook schemes, tenant Models read with .unscoped(), accessibility checks). MCP clients pick up the new tools (docs search, the UI kit, design and accessibility review, profiling, webhooks, teams, upgrade and deploy checks, and the link to your running pyweb dev), prompts and resources the next time they start pyweb mcp; see AI assistants & MCP. Tool arguments are now checked against each tool's schema, so a client that sent extra arguments gets an error that names them.
#Upgrading from 0.4 to 0.5
PYWEB_STRICT_DEPRECATIONS=1 turns every deprecation warning into an error. Use it in CI to find the last uses of old APIs.
#Data
Models. 0.4 Models keep working. Rows still read like dicts (row["name"]) and as attributes (row.name). Two things change:
Model.configure("app.db")is deprecated. Give the app its database instead (app = App(database="sqlite:///app.db")), and every Model uses it. In production,DATABASE_URLreplaces that URL, so you never edit the code to deploy.- In production, a Model with no database is an error. 0.4 quietly used an in-memory SQLite database, which loses everything on restart.
Raw SQL. pyweb.db.connect(...) and db.execute(...) are unchanged. You can move tables to Models one at a time: pyweb db adopt records the current schema as the first migration, then pyweb db diff takes over.
SQLite now enforces foreign keys and uses write-ahead logging. An app whose data already breaks a foreign key sees an error on the next write to that row. PRAGMA foreign_key_check lists such rows.
Migrations. The 0.4 .sql migrations and their journal still work, and can sit next to the new Python migrations that pyweb db diff writes. pyweb db migrate and rollback are now upgrade and downgrade; the old names still work.
#Server functions
Parameter rules are now enforced on every call. If a parameter is annotated Annotated[str, Field(max=40)], a call that breaks the rule gets a 422 with the error for that field. 0.4 checked only the type. Clients that sent values outside the rules now get an error instead of silently passing.
#Jobs
pyweb.jobs became a package. Queue, RedisQueue and @task still work, but they are in memory: a restart loses queued work. Durable jobs replace them:
@app.job(retries=5)
def send_invoice(order_id: int): ...
send_invoice.enqueue(order.id) # was: queue.enqueue(send_invoice, order.id)pyweb serve runs them in the same process unless you run pyweb worker separately (then set PYWEB_WORKER=0 on the web processes). See Background jobs.
#Serving and deploying
pyweb serveis PyWeb's own server: WebSockets, keep-alive, and--workers Nprocesses. It listens on$PORTwhen set (every platform sets it).pyweb serve --app module:factorykeeps the old threaded server.PYWEB_MAX_CONNECTIONSdefaults to 10,000 per process (it was 256).pyweb deploy TARGETreplacespyweb deploy --target T --compose. The old flags still work. Runpyweb deploy compose --planto see what the new planner would write: it adds a worker, Postgres or Redis when your app needs them. Regenerate your files rather than editing the old ones.
#Requests and responses
X-Request-Idis now the W3C trace id (32 hex characters), the same id your logs and traces carry. Behind a proxy you trust (PYWEB_TRUST_PROXY), an incomingX-Request-Idis kept./metricsand/__pyweb/metricsanswer Prometheus scrapes. In production they needPYWEB_METRICS_TOKEN; without it they are a 404. If your app has its own page at/metrics, your page still wins.- Logs are JSON lines in production (
PYWEB_LOG_FORMAT=textkeeps readable lines). The olderpyweb.observabilityclasses still work.
#Security changes
- Tokens are signed with purpose keys only. 0.4.4 still accepted sessions and feed tokens signed with the raw
PYWEB_AUTH_SECRET, so that upgrading from 0.4.3 signed nobody out. 0.5 doesn't. Visitors whose session cookie dates from 0.4.3 or earlier sign in once more. If your code callsauth.issue_session(data, secret)itself, passpyweb.keys.derive(secret, "session")instead (or usesession.login()).pyweb upgrade --checkpoints at those calls. - Stricter Content-Security-Policy. Inline
<style>blocks are allowed by their hash instead of'unsafe-inline', and forms may post only to your own site (form-action 'self').style="..."attributes still work. If a page posts a form to another site (a payment provider, say), add that site toPYWEB_CSP. pyweb checkalso warns about SQL built from strings, pages that readauth.user().namewithoutlogin=True, and Models that belong to a user but have no row policy.pyweb check --strictfails on any warning.
#Accounts
Apps that keep their own login code (like the 0.4 auth example) are unaffected. To move to the auth kit, app.use_auth() adds the users table, sign-in pages and /admin. The session cookie and its secret are the same, but the kit identifies people by user id, so sessions your own code started (usually with an email as the id) don't match an account: people sign in once more. In production the kit needs PYWEB_ORIGIN (the site's address) for the links in its emails. pyweb check --production tells you if it's missing.
#Editors and assistants
Update the VS Code extension to 0.5 for the data features (Model completion, form fields, N+1 and migration warnings). MCP clients pick up the new tools (pyweb_db_schema, pyweb_db_query, pyweb_migrations, pyweb_jobs, pyweb_requests) the next time they start pyweb mcp.