Skip to content

Installation

Prerequisites, version pins, extras, host adapters, and troubleshooting.

1.1 is published

Hedron 1.1.2 is available from PyPI. The documentation describes the stable Hedron 1.1 API contract.

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

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

Which package to install

Package Install Best for
Hedron hedron>=1.1.2,<1.2 FastAPI-native routes, component trees, data applications, and host integration

Hedron 1.1.2 is published on PyPI. The three useful requirement styles are:

Intent Requirement Use it when
Minimum compatible API hedron>=1.0.0 A reusable library supports every documented 1.0 release
Recommended application range hedron>=1.1.2,<1.2 Starting an app on the current stable train
Exact reproducible version hedron==1.1.2 Locking production, CI, or evidence collection

The quickstart uses the compatibility floor so it remains valid across the 1.0 train; the generated project writes the current bounded application range. Commit your resolver's lockfile and review release notes before upgrading. hedron-core, hedron, edron, hedron-data, hedron-charts, and hedron-maps are Stable packages; host/tooling satellites retain their documented Beta or tooling-grade maturity. Capability detail: What’s ready.

Install from PyPI

Prerequisites

  • CPython 3.10–3.14 — verify with python3 --version (Windows: py -3 --version)
  • A clean virtual environment (shared data-science envs with older FastAPI often fail to resolve — see Compatibility for declared vs CI-supported FastAPI/Pydantic bands)
  • uv (recommended) or pip
  • No Node.js required

Installing Python 3.10+

If python3 --version is missing or older than 3.10:

Platform Suggestion
macOS python.org installer, Homebrew brew install python@3.12, or uv python install 3.12
Linux Distro packages (python3.12) or uv python install 3.12
Windows python.org or py -3.12; enable “Add python.exe to PATH”

After installing, reopen the terminal. Prefer python3 -m venv .venv (or uv venv) so system Python is never mixed with the app env. Multiple Pythons: always call the same interpreter for pip / uv / uvicorn (which python3, py -0p on Windows).

Corporate proxy / air-gapped installs

Point pip / uv at your internal index (PIP_INDEX_URL, UV_INDEX_URL, or --index-url). Mirror PyPI wheels for hedron, hedron-core, and matching extras onto that index; retain the documented bounded pins. Offline: download wheels on a connected host (pip download "hedron>=1.0.0") and pip install --no-index --find-links=.... TLS / corporate MITM: install your org’s CA into the env (REQUESTS_CA_BUNDLE / SSL_CERT_FILE, or pip/uv trust-store docs). Codespaces still needs a GitHub account and billed minutes — it is not an offline playground.

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

Then follow the Hedron quick start. To add Hedron to an existing project:

uv init my-hedron-app
cd my-hedron-app
uv add "hedron>=1.0.0" "uvicorn[standard]"

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

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

If PowerShell reports that running scripts is disabled, use Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, or activate with .\.venv\Scripts\activate.bat from cmd.exe.

Then create app.py from the complete listing on Build your first app (manual / no-scaffold path). Prefer hedron new when you want the generated project.

Verify

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

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

PyPI and an in-tree uv sync both resolve the published 1.1.x train.

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

This repository (uv sync)

Clone only if you are contributing or running in-tree examples:

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

This checkout is the 1.1.x source tree. Use uv sync for repository development and the published-compatible PyPI requirement hedron>=1.0.0 for application projects.

See Contributing.

Optional extras

You only need hedron (+ uvicorn) for Hello and most CRUD/admin apps. Install extras only when you need them. Full catalog: Optional packages.

Registry extras use the same PyPI pin as the flagship:

pip install "hedron[data]>=1.0.0"
pip install "hedron[charts]>=1.0.0"
pip install "hedron-sample-kit>=0.2.3,<0.3"
Extra When you need it Package docs
hedron[data] DataTable / DataEditor / data sources hedron-data
hedron[dev] Component Explorer (/hedron-explorer/) hedron-explorer
hedron[charts] First-party / Matplotlib charts hedron-charts
hedron[maps] First-class maps (hedron-maps) hedron-maps
hedron-flask / hedron-django Flask or Django host (no FastAPI at runtime) Flask · Django

Other extras (jinja, auth, mcp, gradio, maps, elements Beta for Supported inventory, Workbench/Posit, notebook, native): Packages.

Charts and the sample plugin have explicit compatibility floors. Versions through 0.1.5 of the sample kit target older cores. Details: Compatibility · hedron-charts · Charts and HTMX.

hedron[browser] needs Playwright browsers

The [browser] extra installs the Playwright Python package. You must also download browser binaries once per environment:

pip install "hedron[browser]>=1.0.0"
playwright install chromium

Without playwright install, browser tests fail with missing-browser errors. Adopter apps do not need [browser] — it is for testing helpers. Contributors: see Contributing.

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.

Common install problems

Symptom Fix
Python older than 3.10 Hedron requires 3.10–3.14. Check with python3 --version, then install a supported interpreter (see Prerequisites above).
hedron: command not found Use python -m hedron …, uvx --from "hedron>=1.0.0" …, or see FAQ / Troubleshooting
ModuleNotFoundError: hedron Same interpreter as uvicorn; activate the venv, then pip install -e . / uv sync — Troubleshooting
FastAPI / pip resolver conflict Use a clean venv. Shared data-science envs with older FastAPI often fail. See pin conflicts and Troubleshooting
uv add / “No pyproject.toml” Create a project first, or use hedron new (FAQ)
Wrong / old version Upgrade: pip install -U "hedron>=1.0.0" — Troubleshooting
Port 8000 already in use Pick another port: uvicorn app:app --reload --port 8001, or stop the other process.
CSRF 403 on first POST Seed cookie with a GET — Troubleshooting
Cannot import DataTable Install hedron[data] — Troubleshooting
Need charts Install hedron[charts]>=1.0.0 — Compatibility
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.

Supported environments

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