Hedron
Build admin tools, CRUD apps, and dashboards in Python—without building a separate frontend.
Hedron is a server-rendered UI framework for FastAPI. Routes return Python components, Hedron renders safe HTML, and HTMX updates just the part of the page that changed. You keep FastAPI's routing, dependency injection, middleware, and JSON APIs; you do not need a Node.js toolchain or a full-script rerun model.
Requires Python 3.11–3.14. The latest public PyPI release is hedron>=0.66.2,<0.67
(v0.66.2); the repository checkout is the v0.67.0 beta train.
The fastest path uses
uv:
uvx --from "hedron>=0.66.2,<0.67" hedron new my-hedron-app
cd my-hedron-app
uv sync
uv run uvicorn app:app --reload
Open http://127.0.0.1:8000, then click Refresh status. Only the status region is returned and swapped into the page.
The generated app (from hedron new) is ordinary Python:
import os
from datetime import UTC, datetime
from hedron import Hedron, Stack, Text, html
app = Hedron(
title="Hedron App",
security="standard",
explorer="off",
session_secret=os.environ.get("HEDRON_SESSION_SECRET", "replace-in-production"),
)
@app.refreshable("/status")
def status():
stamp = datetime.now(UTC).strftime("%H:%M:%S UTC")
return html.div(
Text(f"All systems operational · refreshed {stamp}"),
role="status",
aria={"live": "polite"},
)
@app.command(fallback="/")
def ping():
from hedron import refresh
return refresh(status).toast("Refreshed")
@app.screen("/", title="Home")
def home():
return Stack(
Text("Hello from hedron new"),
status(),
status.refresh_button("Refresh status"),
ping.button("Ping"),
)
Prefer @app.screen for new apps. Use explicit Page + @app.page only when you need
full Page constructor control
(docs).
Undeclared HTMX targets fail closed.
Follow the first-app walkthrough or browse the single-file examples.
What Hedron gives you
| Need | Hedron provides |
|---|---|
| Server-rendered UI | Pages, layouts, forms, tables, dialogs, status views, and media components |
| Partial-page interaction | Declared HTMX fragments, out-of-band updates, progressive-enhancement paths, and target allowlists |
| FastAPI integration | Normal routes, dependencies, middleware, lifespan hooks, responses, and OpenAPI alongside UI routes |
| Safer defaults | Contextual escaping, explicit URL/HTML trust boundaries, CSRF profiles, and conservative caching |
| Production building blocks | Polling jobs, diagnostics, testing helpers, build manifests, deployment guidance, and Flask/Django adapters |
Your application still owns authentication, authorization, persistence, tenancy, and deployment. Hedron is not an ORM, identity provider, hosted service, or client-side SPA runtime.
When it fits
Choose Hedron when you want to build forms, internal tools, admin surfaces, or dashboards as a conventional web application while keeping most UI code in Python components. It is especially useful when raw FastAPI plus Jinja plus HTMX would leave you assembling the same rendering, fragment, CSRF, asset, and component conventions yourself.
Choose Streamlit for notebook-style, full-script-rerun data apps. Choose raw FastAPI and templates when you do not want a component framework. Choose a client-side framework when the product genuinely needs a large browser-side state model.
Coming from Streamlit? Start with the migration center.
Install
The latest installable PyPI release is hedron>=0.66.2,<0.67. The repository checkout
provides the verified 0.67.0 beta train. Use uv sync when working from a checkout.
uv add "hedron>=0.66.2,<0.67" "uvicorn[standard]"
# or
python -m pip install "hedron>=0.66.2,<0.67" "uvicorn[standard]"
Package maturity: Beta · Stable train: 0.66.x · Repository beta tip: 0.67.0 · Latest PyPI release: 0.66.2 · Application pin: >=0.66.2,<0.67
Before deploying, read What's ready today and the shipping guide. Polling is the supported production status-update path; SSE and WebSocket helpers remain experimental.
Add only what you need
The base package includes the FastAPI application, Python UI components, HTML renderer, HTMX interactions, security profiles, and CLI. Integrations are optional:
| Install | Adds |
|---|---|
hedron[data] |
DataTable and DataEditor |
hedron[charts] |
Charts with a compatible satellite floor |
hedron[maps] |
First-class maps (hedron-maps) |
hedron[jinja] |
Optional .hdj templates |
hedron[dev] |
Component Explorer |
hedron[extras] |
Curated workbenches |
hedron[auth] |
Authlib OIDC helpers |
hedron[markdown] |
Markdown rendering and sanitization |
hedron[native] |
Optional Beta native acceleration |
hedron[mcp] |
Beta MCP projection (Supported inventory; mutations Experimental) |
hedron[notebook] |
Beta tooling-grade localhost preview; not a production server |
hedron[gradio] |
Beta allowlisted Gradio/Hugging Face client interoperability |
hedron[elements] |
Beta Web Component ABI (Supported inventory only) |
For example:
uv add "hedron[data,dev]>=0.66.2,<0.67"
Charts require the fixed compatible floor:
uv add "hedron[charts]>=0.66.2,<0.67"
See the full installation and extras guide and the compatibility matrix.
Already have a FastAPI app?
You can mount Hedron's router and static assets without replacing your application:
from fastapi import FastAPI
from hedron import HTML, HedronRouter, Text, hedron_response, mount_hedron_static
from hedron.security.policy import SecurityPolicy
app = FastAPI()
app.state.hedron_security = SecurityPolicy.from_name("standard")
mount_hedron_static(app)
ui = HedronRouter()
@ui.get("/hello", **hedron_response())
def hello():
return HTML(Text("Hello from Hedron"))
app.include_router(ui)
Read the existing-FastAPI guide.
Flask and Django hosts are available through
hedron-flask and
hedron-django; both share the framework-neutral
hedron-core renderer.
CLI
python -m hedron new demoapp
python -m hedron --app app:app routes
python -m hedron --app app:app components
python -m hedron --app app:app preview home
python -m hedron --app app:app check
python -m hedron --app app:app graph
Learn more
License
MIT. See the license.
1 maintainer
Release files for hedron 0.67.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hedron-0.67.0.tar.gz | 301.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hedron-0.67.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 667.9 kB
Release files / hedron-0.67.0.tar.gz
| Download URL | hedron-0.67.0.tar.gz |
|---|---|
| Size | 301.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
266deb467b02335a86aa4336a4eaaa135973276f593f652ade2e207c42b1c46e
|
|
BLAKE2b-256 checksum How to use checksums |
8862f07ddac0a4fc7f9cf63812f27506b3a21794126d5731ef95434a729b728e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / hedron-0.67.0-py3-none-any.whl
| Download URL | hedron-0.67.0-py3-none-any.whl |
|---|---|
| Size | 366.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0441d76d960fb69bc61f3d2c0fcf28f0146c4079d26c796932f2d680affaafa6
|
|
BLAKE2b-256 checksum How to use checksums |
193bfefdae2abc82fc398ee51dcb378917546365af3b3daae247801e743398d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
