PyWeb

Full-stack web apps in one Python file. Server-rendered pages, reactive browser UI compiled from Python, and typed calls to server functions, without a JavaScript toolchain.

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)     # 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>

pip install pyweb-stack   # imported as `pyweb`
pyweb dev app.pyweb        # http://localhost:8000

Why PyWeb

• Interactions run in the browser. Handlers and expressions are compiled to small JavaScript modules; the server is only contacted when your code calls a @server function. No WebSocket per user, no multi-megabyte Python runtime in the browser.
• Every page is server-rendered. Complete HTML on first paint, real data from your database, good for SEO and slow devices.
• You never write an API layer. @server functions get endpoints, argument validation, typed errors and generated browser calls.
• Plain 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.
• Boundaries are checked. Database handles, imports and secrets can't leak into browser code: it's a compile error with a line number. pyweb inspect explains where every name runs and why.
• Stateless servers. Signed-cookie sessions and plain HTTP RPC scale horizontally behind any load balancer. Deploy with pyweb serve, uvicorn/gunicorn (ASGI) or the generated Dockerfile.

A typical interactive page ships under 1 KB of page code plus a ~10 KB (gzip) runtime that's cached across pages. Pages without interactivity ship no JavaScript.

Is it for you?

Good fit: internal tools, admin panels, dashboards, CRUD apps, small SaaS products and content sites with interactive parts, built by people who'd rather stay in Python.

Not a fit: large client-heavy single-page apps that need the npm ecosystem (use React/Svelte/Vue), or running scientific Python in the browser (use Pyodide/PyScript). See the comparison and current limitations.

Build it with AI

PyWeb ships an MCP server so AI assistants can scaffold, check, inspect, render and test your app, with errors that come back as line numbers and fix hints:

claude mcp add pyweb -- pyweb mcp          # Claude Code

{ "mcpServers": { "pyweb": { "command": "pyweb", "args": ["mcp"] } } }

(the JSON is for Cursor, Claude Desktop, VS Code and other MCP clients). pyweb new myapp --template todo also writes AGENTS.md and CLAUDE.md so coding agents follow PyWeb's rules, and the docs site publishes llms-full.txt. See AI assistants & MCP.

Documentation

The same docs are published at maanavkrishna.github.io/PyWeb, with compiler output shown next to each example.

Examples

Each runs with pyweb dev examples/<name>/app.pyweb and is exercised in a real browser by the test suite.

Command line

pyweb new myapp --template todo                  # scaffold (blank|counter|todo|blog|auth|chat)
pyweb dev app.pyweb                              # dev server: live reload + error overlay
pyweb inspect app.pyweb                          # where each name runs, and why
pyweb check app.pyweb                            # compile + security checks for CI
pyweb build app.pyweb --out dist --production    # self-contained, hashed, minified dist/
pyweb serve dist                                 # production server (/healthz, CSP, graceful shutdown)
pyweb mcp                                        # MCP server for AI assistants (stdio)

Status

PyWeb 0.1 is the first public release (beta). The language, server API, RPC protocol and CLI are documented and tested, and changes to them are announced in the changelog (see stability). The test suite covers the parser, the Python→JavaScript translation (differentially, against CPython), the reactive runtime, server rendering, RPC, sessions, every example app in Chromium, and the database/Redis layers against real Postgres, MySQL and Redis servers, on Python 3.10–3.13.

Authors

Built by MaanavKrishna and Claude.

Contributing

See CONTRIBUTING.md. Security reports: SECURITY.md. License: MIT.