Skip to content

Installation

Prerequisites, extras, host adapters, and troubleshooting.

The golden-path Hello copy-paste lives on Build your first app (hedron new → Hello → Refresh). Use this page for version checks, optional extras, Flask/Django adapters, and install failures.

Session secrets and [tool.hedron] keys: Configuration.

Prerequisites

  • CPython 3.11–3.14 — verify with python3 --version (Windows: py -3 --version)
  • Use a clean virtual environment (Hedron needs FastAPI >=0.141.1,<0.142)
  • uv (recommended) or pip
  • No Node.js required
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell): irm https://astral.sh/uv/install.ps1 | iex
# Then reopen the shell and confirm: uv --version

Prefer python3 on macOS/Linux and py -3 on Windows when python is missing or points at the wrong interpreter. Prefer python -m hedron so PATH never matters.

Verify

After following Build your first app:

uv run python -c "import hedron; print(hedron.__version__)"

python -c "import hedron; print(hedron.__version__)"

Expect 0.20.0 (or a newer 0.20.x patch) on this train. Last published PyPI/git is v0.20.0. Pin with hedron>=0.20.0,<0.21 for production.

If hedron is not found after install, prefer python -m hedron … or see Troubleshooting.

Common install problems

Symptom Fix
hedron: command not found Use python -m hedron …, uvx --from "hedron>=0.20.0,<0.21" …, or see FAQ / Troubleshooting
ModuleNotFoundError: hedron Same interpreter as uvicorn; activate the venv, then pip install -e . / uv sync — Troubleshooting
FastAPI / pip resolver conflict Empty venv recommended; see pin conflicts and Troubleshooting
uv add / “No pyproject.toml” Create a project first, or use hedron new (FAQ)
Wrong / old version pip install -U "hedron>=0.20.0,<0.21" — Troubleshooting
CSRF 403 on first POST Seed cookie with a GET — Troubleshooting
Cannot import DataTable / charts Install extras — Troubleshooting
Explorer 404 Install hedron[dev] and enable development Explorer — Troubleshooting
Production missing manifest Run hedron build before HEDRON_ENV=production — Troubleshooting

Full list: Troubleshooting · Failure gallery · FAQ.

If install fails on FastAPI/Pydantic

Prefer a clean virtual environment for your first app (do not reuse a shared env that already pins an older FastAPI). Then see Dependency pin conflicts for the Supported vs declared FastAPI/Pydantic ranges.

Optional extras

Install extras only when you need them:

Extra When you need it Package docs
hedron[data] DataTable / DataEditor / data sources hedron-data
hedron[charts] LineChart and visualization adapters (Alpha) hedron-charts
hedron[jinja] Optional HDJ (.hdj) templates hedron-jinja
hedron[dev] Component Explorer (/hedron-explorer/) hedron-explorer
hedron[conformance] Language-neutral conformance kit / CLI runner hedron-conformance
hedron[native] Optional Rust HTML-escape acceleration (Alpha) hedron-native
hedron[extras] Curated extras / workbenches hedron-extras
hedron[notebook] Alpha server-side notebook preview hedron-notebook
hedron[mcp] Alpha deny-by-default MCP projection hedron-mcp
hedron[gradio] Alpha Gradio client interop (experimental) hedron-gradio
hedron[otel] Optional OpenTelemetry tracing helpers —
hedron[markdown] / [code] / [images] / [email] / [sanitize] / [auth] / [browser] Content, Authlib, or test helpers —

Also install directly (no flagship extra): hedron-sample-kit · hedron-sim. Full catalog: Optional packages.

pip install "hedron[data]>=0.20.0,<0.21"          # example
pip install "hedron[charts]>=0.1.0,<0.2"         # Alpha — pin and expect churn
pip install "hedron-charts[plotly]>=0.1.0,<0.2"  # chart backend after charts extra (tip: 0.1.5)

Other hosts

Package Use when
hedron-flask Flask — init_app / Blueprint, page + fragment routing/HTMX Supported
hedron-django Django >=5.2,<6 — forms bridge + QuerySet DataSource Supported
hedron-core Framework-neutral rendering only

Quickstarts: Flask · Django.

Component Explorer

With hedron[dev] installed and explorer="development" on Hedron(...), open /hedron-explorer/ while the app is running. Leave Explorer off in production.

Alternative: manual project

Use this only if you are not using hedron new.

uv init my-hedron-app
cd my-hedron-app
uv add "hedron>=0.20.0,<0.21" "uvicorn[standard]"

mkdir my-hedron-app && cd my-hedron-app
python -m venv .venv
source .venv/bin/activate
python -m pip install "hedron>=0.20.0,<0.21" "uvicorn[standard]"

mkdir my-hedron-app; cd my-hedron-app
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install "hedron>=0.20.0,<0.21" "uvicorn[standard]"

Then create app.py from the quickstart (manual / no-scaffold path).

Supported environments

See the compatibility policy for exact ranges. When evaluating production use, see What’s ready today.

Contributor checkout

git clone https://github.com/eddiethedean/hedron.git
cd hedron
uv sync

See Contributing.