GitHub
New 0.6.3: teams, installable and desktop apps, a UI kit with motion →

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
app.pyweb
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>
Runs in the browserRuns on the serverRendered on the server, updated in the browser
15.0 KBshared runtime, gzip, cached
296 Bpage code for a counter
0 BJavaScript on static pages
47 µsto server-render the todo page
How it works

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
Home.js · compiled from submit()
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
  • @server functions become validated JSON endpoints
  • Sends only the values browser code reads
HTTP · a real request to the app above
GET /
  → runs Home(), renders 0.5 KB of HTML

POST /__pyweb/rpc/sign
  {"args": {"name": "Ada"}}
  → {"result": ["Ada"]}
One file

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 Idea Model is a table, its rules, and the form's fields
  • .policy() keeps people's rows their own, on every query
  • thank.enqueue() is queued only if the request commits
  • .live() sends each new idea to every open tab
Build one in the SaaS tutorial →
app.pyweb
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>
Live demo

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
See its source and generated JavaScript →
localhost:8000
UI kit and motion

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
See its source →
localhost:8000
Why PyWeb

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.

Tooling

Everything around the compiler

AI assistants

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.md and a starter test; the docs ship as llms-full.txt
Set it up →
Claude Code
pip install pyweb-stack
claude mcp add pyweb -- pyweb mcp
Cursor · Claude Desktop · VS Code
{
  "mcpServers": {
    "pyweb": { "command": "pyweb", "args": ["mcp"] }
  }
}
Where it fits

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 →

ApproachYou writeTrade-off
Django / Flask / FastAPI + ReactA Python API and a JavaScript appTwo languages, two builds, a hand-written API in between
Templates + htmxViews, templates, an endpoint per interactionEvery interaction is a round trip; client state is awkward
Reflex, NiceGUI, StreamlitPython onlyUI state lives on the server; every click is a round trip
PyScript / PyodidePython onlyA multi-megabyte runtime before anything is interactive
PyWebOne Python fileBrowser 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.