Introduction
PyWeb lets you build a complete web application in Python, in one file. You write pages as Python functions with HTML-like markup, keep interactive state in ordinary local variables, and mark the functions that must run on the server with @server. The compiler works out what runs where and produces:
- server-rendered HTML for every page, so the first paint is complete and works for search engines and slow devices;
- a small JavaScript module per interactive page, compiled from your Python event handlers and expressions (no Python runtime in the browser);
- typed RPC endpoints for your
@serverfunctions, with generated browser calls, argument validation and structured errors.
Around that core, PyWeb has what a product needs, in the same file:
- Data: Models with relations, a query builder, migrations that write themselves (
pyweb db diff) and row policies that decide who sees which rows. SQLite, Postgres and MySQL. (Data & databases) - Forms:
<Form action={create_post}>takes its fields and rules from the Model, checks them in the browser as you type and again on the server, and works without JavaScript. (Forms & uploads) - Accounts:
app.use_auth()adds sign-up, login, passkeys, magic links, OAuth, two-factor and an admin. (Authentication) - Live updates:
Post.query().live()keeps a list in step with the database in every open tab, sending only the rows that changed. (Live data) - Background work:
@app.joband@app.cron, stored in your database, retried, and queued in the same transaction as the request. (Background jobs) - Teams:
app.use_auth(orgs=True)adds organizations, invitations, roles and plans, andclass Project(Model, tenant=True)keeps each team's rows its own, enforced by the database on Postgres. (Teams & organizations) - A UI kit with motion:
from pyweb.ui import Dialog, DataTable, ...gives accessible, themed components;animate=,exit=andlayoutanimate any element with springs. (UI kit & motion) - Installable and desktop apps:
App(pwa=True)makes an app installable with an offline page and push notifications;pyweb desktopopens it in its own window and packages an installer. (Installable apps, Desktop apps) - Webhooks and files: signed webhooks in and out, and unused uploads cleaned up. (Webhooks & files)
- A dev loop that keeps up: saves update the open page in place with its state kept; Alt-click opens any element's source; Fix with AI and Edit with AI; a time-travel timeline;
pyweb dev --share. (The dev loop) - Shipping:
pyweb deploywrites Docker, Compose, Kubernetes, Fly, Render or Railway files; logs, metrics and traces come built in. (Scaling & deploying) - Security by design: Trusted Types, encrypted fields, rate limits per function, an SSRF-safe
fetchand secret scanning, with every threat listed next to the test that proves its defence. (Security model)
app.pyweb
from pyweb import App, server
app = App(title="Guestbook")
ENTRIES = []
@server
def sign(name: str) -> list:
ENTRIES.append(name.strip() or "anonymous")
return ENTRIES
@app.page("/")
def Home():
entries = list(ENTRIES) # runs on the server for each request
name = "" # bound to the input below: browser state
def submit(): # compiled to JavaScript
entries = sign(name) # calls the server over RPC
name = ""
<main>
<h1>Guestbook ({len(entries)})</h1>
<form onsubmit={submit}>
<input bind={name} placeholder="Your name" />
<button>Sign</button>
</form>
<ul>
for entry in entries:
<li>{entry}</li>
</ul>
</main>What this compiles to
JavaScript
// Home.js
function Home($s) {
const entries = $signal("entries" in $s ? $s["entries"] : null, "entries");
const name = $signal("name" in $s ? $s["name"] : "", "name");
async function submit() {
entries((await $rpc("sign", {"name": name()})));
name("");
}
return [$h("main", null, () => [
$h("h1", null, () => [
$t("Guestbook ("),
$dyn(() => $py.len(entries())),
$t(")")
]),
$h("form", {"onsubmit": submit}, () => [
$h("input", {"$bind": name, "placeholder": "Your name"}),
$h("button", null, () => [$t("Sign")])
]),
$h("ul", null, () => [$list(() => entries(), (entry) => [$h("li", null, () => [$t($py.text(entry))])])])
])];
}
$mount("Home", Home);Output
page Home route=/
browser entries reactive state: assigned in submit(); initial value computed on the server and sent
browser name reactive state: bound to an input (line 25); literal initial value
browser submit event handler (compiled to JavaScript)
rpc POST /__pyweb/rpc/sign (name: str) -> listHTML
<main>
<h1>Guestbook ()</h1>
<form>
<input value="" placeholder="Your name"><button>Sign</button>
</form><ul>
</ul></main>Run it with pyweb dev app.pyweb and open http://localhost:8000.
#The problem it solves
Python developers who need a real web UI usually pick one of these:
| Approach | What you write | The cost |
|---|---|---|
| Django / Flask / FastAPI + a JS framework | Python API and a React/Vue/Svelte app | Two languages, two builds, a hand-written API layer between them |
| Server templates + htmx | Python views, HTML templates, endpoints per interaction | Every interaction is a server round trip; client state is awkward |
| Server-driven Python UI (Reflex, NiceGUI, Streamlit) | Python only | UI state lives on the server; each click is a network round trip over a WebSocket, and servers hold per-user sessions |
| Python in the browser (PyScript / Pyodide) | Python only | A multi-megabyte runtime download before anything is interactive |
PyWeb takes the architecture of modern JavaScript meta-frameworks (server rendering + fine-grained client reactivity + server functions) and makes Python the source language for all of it:
- Interactions run in the browser. Typing, toggling and filtering update the DOM locally. The network is used only when your code calls a
@serverfunction, or when a page shows live data. - Servers stay stateless. Pages render per request, RPC calls are plain JSON over HTTP and sessions are signed cookies, so any number of processes can sit behind an ordinary load balancer without sticky sessions. Pages with live data open one WebSocket per tab (Server-Sent Events where WebSockets are blocked), and Redis carries changes between processes.
- What ships is small. The shared runtime is about 15 KB gzipped and cached; a typical page adds well under 1 KB. Forms (about 3 KB) and live updates (about 2 KB) load only on pages that use them, and pages without interactivity ship no JavaScript at all.
- Boundaries are explicit and checked. Code that can't run in a browser (database access, imports, secrets) is a compile error with a file and line, not a runtime surprise.
pyweb inspectexplains where every name runs and why.
#When PyWeb is a good fit
- Internal tools, admin panels, dashboards and CRUD apps, including ones that update live as the database changes.
- AI features: chat, summarising, drafting, with replies streamed from your server and keys kept there.
- Product sites and SaaS apps with accounts, data and background work (
pyweb new myapp --template saasstarts one; the SaaS tutorial walks through it). - Teams that know Python and want a web UI without adopting a separate JavaScript stack.
#When to choose something else
- Large single-page apps built around a JavaScript component framework (React/Svelte/Vue component libraries): use that framework directly. Plain npm libraries (charts, maps, editors) work in PyWeb; see npm packages.
- Scientific Python in the browser (NumPy, pandas client-side): use Pyodide/PyScript. PyWeb compiles a defined subset of Python to JavaScript; it does not run CPython in the browser.
- Notebook-style data apps where a script re-running on every interaction is the desired model: Streamlit is purpose-built for that.
#How it works, briefly
- Parse. A
.pywebfile is Python plus markup statements. The parser separates the two, keeping line numbers exact for both. - Classify. For each page, every local variable is classified: signal (changed by an event handler or bound to an input), computed (derived from signals), or constant; and by where its first value comes from: a literal, the browser, or the server.
- Place. Event handlers and markup expressions are compiled to JavaScript. Calls to
@serverfunctions become awaited RPC calls. Everything else stays on the server. - Render. On each request the server runs the page function, renders HTML, and embeds only the values the browser code reads as JSON.
- Hydrate. The page's module adopts the server-rendered DOM and attaches live bindings to it; from then on, each signal update touches only the nodes that depend on it.
Read on: Quickstart · Tutorial · The .pyweb language.