Full-stack web apps in one Python file.
PyWeb is a Python web framework: server-rendered pages, a reactive UI compiled from Python, and typed calls to server functions, plus the rest of a product (data, forms, accounts and teams, live updates, background jobs, deploys) in the same file. No JavaScript toolchain, no runtime download.
pip install pyweb-stack
from pyweb import App, server app = App(title="Guestbook")ENTRIES = [] @serverdef sign(name: str) -> list: ENTRIES.append(name.strip() or "anonymous") return ENTRIES @app.page("/")def Home(): entries = list(ENTRIES) # computed on the server per request name = "" # bound to the input: browser state def submit(): # compiled to JavaScript entries = sign(name) # typed RPC to the server 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>One file. The compiler puts each line where it belongs.
Write pages as Python functions with markup. PyWeb splits them: handlers become a tiny browser module, everything else stays on your server. This is the output for the app above.
In the browser
A 425 B module (gzip) plus the shared runtime.
- Variables your handlers change become signals
- Handlers compile to JavaScript with Python semantics
- Hydrates the server's HTML in place: nothing is rebuilt
async function submit() {
entries((await $rpc("sign", {"name": name()})));
name("");
}On the server
Plain Python, per request: your database, files and secrets stay here.
- Renders complete HTML with real data
@serverfunctions become validated JSON endpoints- Sends only the values browser code reads
GET /
→ runs Home(), renders 0.5 KB of HTML
POST /__pyweb/rpc/sign
{"args": {"name": "Ada"}}
→ {"result": ["Ada"]}A whole product, still one file
Accounts, a table with rules, a form, a background job and a list that updates in every open tab: 44 lines.
app.use_auth()adds sign-up, passkeys, OAuth and/admin- The
IdeaModel is a table, its rules, and the form's fields .policy()keeps people's rows their own, on every querythank.enqueue()is queued only if the request commits.live()sends each new idea to every open tab
from pyweb import App, Field, Form, Input, Model, Submit, server
from pyweb.authkit import User
app = App(title="Feedback", database="sqlite:///app.db")
auth = app.use_auth() # sign-up, passkeys, OAuth, /admin
class Idea(Model):
text: str = Field(min=3, max=280)
votes: int = 0
author: User = Field(readonly=True)
def own(user, idea):
return user is not None and idea.author_id == user.id
Idea.policy(write=own) # only its author can change an idea
@server(login=True)
def share(idea: Idea): # the form's fields come from Idea
idea.author = auth.user()
idea.save()
thank.enqueue(idea.id) # runs after the request commits
@app.job(retries=3)
def thank(idea_id: int):
print(f"thanks for idea {idea_id}")
@app.page("/", login=True)
def Ideas():
ideas = Idea.query().order("-id").live() # every open tab
<Form action={share}>
<Input name="text" placeholder="Your idea" />
<Submit>Share</Submit>
</Form>
<ul>
for idea in ideas:
<li>{idea["text"]} ({idea["votes"]})</li>
</ul>
This is a real PyWeb app
The todo example (started with three items), compiled by PyWeb and running right here: 2351 bytes of page code.
- Add items, tick them off, switch filters
- Everything updates locally, with no network round trips
- The same file renders the first paint on the server
Components and animation, from Python
Accessible dialogs, menus, pickers, tables and charts from pyweb.ui; springs, exit animations,
layout changes and drag from plain attributes. Restyle all of it with one Theme(...).
- Open the dialog, the menu and ⌘K
- Switch to Motion: hover, drag, reorder
- Flip the Dark switch
The good parts of modern web stacks, in Python
Interactions run in the browser
Handlers and expressions compile to small JavaScript modules. Typing, toggling and filtering update the page locally; the network is used for @server calls and live data. No Python runtime download.
Every page is server-rendered
Complete HTML on first paint with real data from your database, then hydrated in place. Layouts keep their state while links load without a full reload.
No API layer to write
@server functions get endpoints, argument validation, typed errors and generated browser calls.
A UI kit and motion, built in
Sixty accessible components in the spirit of shadcn/ui and Radix, and spring animations like motion.dev: animate=, exit=, layout, gestures and drag. One Theme(...) restyles everything, sign-in and /admin included.
Variables are state
The compiler sees which variables your handlers change and makes exactly those reactive. Updates touch only the DOM nodes that read them.
Models and migrations
class Post(Model) is a table with rules, relations and row policies, on SQLite, Postgres or MySQL. pyweb db diff writes the migration; N+1 loops are an error while you develop.
Forms that check themselves
<Form action={save}> takes its fields and rules from the Model, checks them as you type and on the server, blocks double submits and works without JavaScript.
Accounts in one line
app.use_auth(): sign-up, passkeys, magic links, GitHub/Google/Microsoft, two-factor, throttling, an audit log and /admin for every Model.
Teams
app.use_auth(orgs=True): organizations, invitations, roles and plans. class Project(Model, tenant=True) keeps each team's rows its own, in every query, live list and job, and on Postgres the database enforces it too.
Installable and desktop
App(pwa=True) makes the app installable, with an offline page and Web Push. pyweb desktop opens the same file in its own window, and pyweb build --desktop packages an installer.
Live, row by row
Post.query().live() updates every open tab when the data changes, one changed row at a time over one WebSocket. Server functions that yield stream AI replies, with a Stop that really stops.
Background jobs and schedules
@app.job and @app.cron, stored in your database, retried with backoff, and queued in the request's transaction, so a rollback queues nothing.
Security by design
Secrets and database handles can't reach browser code: it's a compile error. Trusted Types, encrypted fields, rate limits per function, an SSRF-safe fetch, signed webhooks and secret scanning; a threat model lists every threat with its test.
A dev loop that keeps up
Save and the open page changes in place, every component keeping its state. Alt-click any element to open its line in your editor; Fix with AI on error pages, a timeline to step back through every change, and pyweb dev --share for a link someone else can try. The dev loop
npm without Node
pyweb add chart.js/auto vendors a package for browser code, pinned in pyweb.lock. No node_modules, no bundler.
Ship it, then watch it
pyweb deploy fly (or docker, compose, k8s, render, railway) plans Postgres, workers and Redis for you. JSON logs, Prometheus metrics and OpenTelemetry traces are built in.
Everything around the compiler
pyweb deploy: the tutorial builds and ships one.Follow it →Built for building with AI
One file, plain Python, and a compiler that answers mistakes with a line number and a fix. The built-in MCP
server gives Claude Code, Cursor and other assistants 31 tools: scaffold and check apps, search the docs, build
with the UI kit, render pages and call server functions as any signed-in member, review pages in light, dark
and on a phone with an accessibility audit, profile them, run the tests, read the schema and data, and check
security and the deploy plan. While you run pyweb dev, they see its live errors and logs.
- Step-by-step prompts: add teams, a design pass, a security review, debug a page
- stdio or Streamable HTTP (
pyweb mcp --http), MCP 2025-11-25 - New projects include
AGENTS.md,CLAUDE.mdand a starter test; the docs ship as llms-full.txt
pip install pyweb-stack
claude mcp add pyweb -- pyweb mcp{
"mcpServers": {
"pyweb": { "command": "pyweb", "args": ["mcp"] }
}
}Made for Python developers who ship web UIs
Internal tools, dashboards, CRUD apps and SaaS products, without adopting a JavaScript stack. For large client-heavy single-page apps, use a JavaScript framework; for scientific Python in the browser, use Pyodide. Read the full comparison →
| Approach | You write | Trade-off |
|---|---|---|
| Django / Flask / FastAPI + React | A Python API and a JavaScript app | Two languages, two builds, a hand-written API in between |
| Templates + htmx | Views, templates, an endpoint per interaction | Every interaction is a round trip; client state is awkward |
| Reflex, NiceGUI, Streamlit | Python only | UI state lives on the server; every click is a round trip |
| PyScript / Pyodide | Python only | A multi-megabyte runtime before anything is interactive |
| PyWeb | One Python file | Browser code is a compiled subset of Python |
Build something in the next five minutes
Install it, scaffold an app, and open it in your browser. Or skip the install and use the playground.