Pyplet is an application server that lets you create interactive web applications using Python on both the client and server side. Powered by PyScript (Python compiled to WebAssembly), Pyplet brings the full power of Python to the browser.
- Pure Python: Write your entire application in Python - no JavaScript required
- Real-time Communication: Built-in WebSocket support for seamless client-server interaction
- Modern Async: Leverages Python's
async/awaitfor responsive applications - Browser-Native: Client code runs directly in the browser via WebAssembly
- Shared Code: Reuse Python modules between client and server
- Python ≥3.12
uv(recommended) orpip
The recommended way to install Pyplet is via uv.
-
Install venv
uv venv
-
Activate the venv
source ./venv/bin/activate -
Install Pyplet
uv pip install pyplet
pyplet init my_appThis creates a new project in apps/my_app/ with two files:
my_app_client.py- Python code that runs in the browsermy_app_server.py- Server-side Python logic
pyplet startThen open your browser to http://localhost:8080 to see your apps!
Here's a minimal Pyplet app showing real-time communication:
hello_client.py, runs in the browser:
import pyplet
from js import document
container = document.getElementById("container")
class MyClientApp(pyplet.client.ClientApplication):
async def websocket_client_loop(self, ws: pyplet.WebSocket):
# Receive message from server
message = await ws.receive()
container.innerText = message.decode()
# Send message back to server
await ws.send(b"Hello from the browser!")hello_server.py, runs on the server:
import pyplet
class _(pyplet.server.ServerApplication):
async def websocket_server_loop(self, ws: pyplet.WebSocket):
# Send message to client
await ws.send(b"Hello from the server!")
# Receive client's response
response = await ws.receive()
print(f"Client says: {response.decode()}")You can create reusable components that work on both client and server.
# Server side download component
download("./static/static_file.txt", "Download from server"),
# Client side download component (from virtual file system, i.e., from_vfs=True)
download(
"./public/vfs_file.txt", "Download from client", from_vfs=True
),You must put you files in the right project folder in the static directory
(the name of the directory must be static)
for the server, and in the public directory for the client
(the name of the directory can be changed, but should not be static).
The from_vfs flag tells Pyplet to look for the file in the virtual file
system (client-side) instead of the server's filesystem.
Pyplet uses a unique dual-runtime architecture:
- Server-side: Standard CPython running Tornado web server
- Client-side: Python code compiled to WebAssembly (e.g., via PyScript using Pyodide), running in the browser
- Communication: WebSocket connection bridges the two environments
┌──────────────────────┐ WebSocket ┌───────────────────────┐
│ Browser (PyScript) │ <───────────────────────> │ Server (CPython) │
│ your_app_client.py │ │ your_app_server.py │
└──────────────────────┘ └───────────────────────┘
apps/ # Your apps live here
├── auth_rules.json # The authentification rules are defined here
└── app_1/
├── app_1_client.py # The client code
└── app_1_server.py # The server codeEvery app is served at /apps/<project>/<app>, so each one needs a project
to belong to. The layout above is what pyplet init creates: one directory
per project inside the apps root, which is the project's name.
The apps root may also hold the *_client.py / *_server.py files
directly, in which case the root itself is the project and takes its name
from its own directory name:
examples/ # --apps / PYPLET_APPS points here
├── app_1_client.py # served at /apps/examples/app_1
└── app_1_server.pyBoth give the same URLs — pointing --apps at examples/ and pointing it at
that folder's parent are equivalent — and a root that mixes the two yields all
of them. Point the apps root at whichever directory suits your repository:
pyplet start --apps path/to/examples
PYPLET_APPS=path/to/examples pyplet startPyplet supports platform-level OAuth2 / OIDC authentication via Google and Microsoft. When enabled, all pages and WebSocket connections are gated behind a login screen. Auth is opt-in: if no provider is configured the platform runs with no login, exactly as before.
1. Register an OAuth app with your provider and obtain a client ID and secret. Set the callback URL to:
http://<your-host>/oauth/callback
2. Set environment variables:
# Required & persistent in production — generate once and keep it stable.
# Under PYPLET_REQUIRE_AUTH=1 the server refuses to boot when this is unset
# (a per-process random secret logs out every user on each restart):
export PYPLET_COOKIE_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
# Google
export OAUTH_GOOGLE_CLIENT_ID=your-client-id
export OAUTH_GOOGLE_CLIENT_SECRET=your-client-secret
# Microsoft / Entra ID (can be set alongside Google)
export OAUTH_MICROSOFT_CLIENT_ID=your-client-id
export OAUTH_MICROSOFT_CLIENT_SECRET=your-client-secret
export OAUTH_MICROSOFT_TENANT=common # or your tenant ID3. Start the server — a login page with provider buttons appears automatically.
To restrict which apps each user can see, create apps/auth_rules.json — a
JSON array of ["project/app regex", "email regex"] pairs:
[
[".*", "@mycompany\\.com$"],
["public/demo", ".*"]
]Rules are evaluated in order; the first matching rule grants access.
The first regex is matched against the combined "project/app" string;
the second against the user's email address.
If no rule matches, access is denied.
Override the rules file path with PYPLET_AUTH_RULES_FILE.
Deny-by-default (fail closed): when authentication is enabled but the rules
file is missing, access is denied to every app — ship auth_rules.json
in your deploy artifact. (When auth is fully disabled — local dev with no
provider — a missing file still allows all apps, so an un-authenticated local
run works.)
As an alternative (or complement) to OAuth, users can sign in by entering their e-mail address and clicking a single-use link delivered to their inbox — no password required.
Configure an SMTP server to enable it:
export MAGICLINK_SMTP_HOST=smtp.example.com
export MAGICLINK_SMTP_PORT=587 # default
export MAGICLINK_SMTP_USER=noreply@example.com
export MAGICLINK_SMTP_PASSWORD=secret
export MAGICLINK_FROM=noreply@example.com # optional, defaults to SMTP_USER
export MAGICLINK_TOKEN_TTL=900 # seconds (default: 15 min)
# Set to "0" to disable STARTTLS (not recommended):
# export MAGICLINK_SMTP_TLS=0Magic-link and OAuth providers can be active simultaneously — the login page shows all available methods.
The ACL rules file applies to magic-link logins exactly the same way it does
for OAuth: the user's e-mail address is matched against the email_regex
column of each rule.
Because magic-link mints a session for any e-mail that can receive the
link, it is refused at boot on the production profile (PYPLET_REQUIRE_AUTH=1,
below) unless you opt in explicitly with PYPLET_ALLOW_MAGICLINK=1.
On any non-local deployment, set PYPLET_REQUIRE_AUTH=1. With it, the server
refuses to boot (exits non-zero with a logged error) rather than silently
serving anonymously when the auth config is misdelivered — specifically when
no auth method is configured, when auth_rules.json is missing, or
when magic-link is enabled without PYPLET_ALLOW_MAGICLINK=1. Without the
flag (the default), a deployment with no provider still starts but logs a loud
WARNING that every request is served anonymously.
Three further production-profile guards ship with this posture. The server
refuses to boot when PYPLET_DEBUG=1 under PYPLET_REQUIRE_AUTH=1 —
Tornado debug mode enables autoreload and exposes traceback pages, so set
PYPLET_DEBUG=0 in production. Behind a TLS-terminating reverse proxy,
app.listen trusts X-Forwarded-For/X-Forwarded-Proto (xheaders) and
WebSocket upgrades are origin-checked against the PYPLET_URL host
(same-origin when PYPLET_URL is unset). At login, OIDC id_tokens are
verified against the provider JWKS (RS256 signature, issuer, audience and
expiry) before a session is established.
| Variable | Description |
|---|---|
PYPLET_COOKIE_SECRET |
Secret for signing session cookies |
PYPLET_SECURE_COOKIES |
Force Secure attribute on auth cookies: 1/0 |
PYPLET_REQUIRE_AUTH |
Fail-closed switch: 1 refuses boot, default 0 |
PYPLET_ALLOW_MAGICLINK |
Opt magic-link IN on require-auth, default 0 |
PYPLET_SESSION_TTL_DAYS |
Session cookie lifetime in days, default 1 |
| OAuth — Google | |
OAUTH_GOOGLE_CLIENT_ID |
Google OAuth2 client ID |
OAUTH_GOOGLE_CLIENT_SECRET |
Google OAuth2 client secret |
| OAuth — Microsoft | |
OAUTH_MICROSOFT_CLIENT_ID |
Microsoft / Entra ID client ID |
OAUTH_MICROSOFT_CLIENT_SECRET |
Microsoft / Entra ID client secret |
OAUTH_MICROSOFT_TENANT |
Tenant ID or common (default: common) |
| Magic-link | |
MAGICLINK_SMTP_HOST |
SMTP server hostname (required to enable magic-link) |
MAGICLINK_SMTP_PORT |
SMTP port (default: 587) |
MAGICLINK_SMTP_USER |
SMTP login username |
MAGICLINK_SMTP_PASSWORD |
SMTP login password |
MAGICLINK_SMTP_TLS |
Use STARTTLS: 1 (default) or 0 for plain SMTP |
MAGICLINK_FROM |
Sender address (defaults to MAGICLINK_SMTP_USER) |
MAGICLINK_TOKEN_TTL |
Token validity in seconds (default: 900 = 15 min) |
| ACL | |
PYPLET_AUTH_RULES_FILE |
ACL rules path (default: apps/auth_rules.json) |
PYPLET_COOKIE_SECRET must be persistent and is required under
PYPLET_REQUIRE_AUTH=1 (the server refuses to boot when unset);
PYPLET_SECURE_COOKIES, when unset, follows the PYPLET_URL scheme.
Pyplet provides utilities for working with the DOM:
from pyplet.shared.dom import create_element
# Create elements programmatically
button = create_element('button', {'class': 'btn btn-primary'}, 'Click me!')Built-in support for Bootstrap UI components:
from pyplet.shared.dom.bootstrap import create_button, create_card
button = create_button('Primary', style='primary')
card = create_card('Card Title', 'Card content goes here')Check whether code is running on server or client:
import pyplet
if pyplet.is_server:
print("Running on server")
elif pyplet.is_client:
print("Running in browser")# Create a new project
pyplet init <project_name>
# Start the development server
pyplet start
# Start server with custom options
pyplet start --port 3000 --address 0.0.0.0
# Start the tutorial
pyplet tutorial
# Run server directly with Python
python -m pyplet.serverServer-wide configuration is managed in pyplet/server/config.py and can be
set via environment variables or CLI flags:
# Using environment variables
export PYPLET_PORT=3000
export PYPLET_ADDRESS=0.0.0.0
pyplet start
# Using CLI flags
pyplet start --port 3000 --address 0.0.0.0Available configuration options:
--address/PYPLET_ADDR- Server address (default:127.0.0.1)--port/PYPLET_PORT- Server port (default:8080)--apps/PYPLET_APPS- Apps directory (default:apps)--debug/PYPLET_DEBUG- Debug mode (default1; must be0in prod)--pyodide-url/PYPLET_PYODIDE- Pyodide CDN URL--url/PYPLET_URL- Custom URL overridePYPLET_WS_MAX_MESSAGE_MB- Max WebSocket frame size MB (default:40)
See the Authentication section for OAuth-related variables.
Pyplet should work in any modern browser that supports WebAssembly:
- Chrome/Edge 57+
- Firefox 52+
- Safari 11+
Pyplet uses:
- Tornado - Async web server
- PyScript - Python in WebAssembly (via Pyodide)
- Cython - Python to C compiler for performance
Edit pyproject.toml under [project].dependencies
Edit pyproject.toml under [project.optional-dependencies].test
Check the apps/template/ directory for a working example demonstrating:
- WebSocket communication
- DOM manipulation
- Async patterns
- Client-server interaction
Since client code runs in PyScript (WebAssembly):
- Not all Python packages are available in the browser
- Some stdlib modules have limited functionality
- The
jsmodule gives direct access to the browser APIs
Pyplet lives in two places, and they are not interchangeable:
- GitLab
seglab/pyplet(CETIC forge,git.cetic.be) is the canonical repository. Development lands there, on the default branchmain, through merge requests. - GitHub
cetic/Pypletis the publication mirror. It is deliberately behind: nothing is developed there, and it is refreshed from GitLabmainby a maintainer when a state is worth publishing.
The flow is one-way: GitLab main → GitHub. A change pushed straight
to GitHub would be overwritten by the next publication.
Contributions are welcome! When contributing:
- Maintain clean separation between client and server code
- Use
async/awaitfor all I/O operations - Test in both server (CPython) and client (PyScript) environments
- Follow the existing naming conventions
- Use the
prek(pre-commit) - Implement tests for the features your are adding
Apache License 2.0 - See LICENSE for details
-
Authors:
- Maxime Istasse (istassem@gmail.com)
- Arthur Lorin (arthur.lorin@cetic.be)
- Erwan Henin (erwan.henin@cetic.be)
- Vincent Stragier (vincent.stragier@cetic.be)
-
Issues: Please report bugs and feature requests via the issue tracker
Future enhancements planned:
- Hot reload during development
- More built-in UI components
- Better error handling and debugging tools
- Enhanced documentation and tutorials
- Package distribution via PyPI
Happy coding with Python everywhere! 🐍✨