django-gandalf
django-gandalf lets you declare multi-step, tree-shaped Django form flows
as readable, composable code.
You build a flow with a small, immutable builder — .step() to add a form,
.branch() to fork on an answer, .expand() to grow steps from an answer —
and mount it as an ordinary Django view. Gandalf handles the per-step URLs,
the session state, back-navigation, editing, file uploads, and running your
completion logic exactly once. When one wizard is not enough, it handles the
task list of wizards too: sections the user does in any order, lists they
grow, sections that unlock or appear because of what they said elsewhere, and
a submit at the end of all of it.
from gandalf.wizard import Wizard, condition
application = (
Wizard()
.step(ApplyingAsForm, name="applying-as")
.branch(
condition(is_organisation, Wizard().step(OrganisationForm, name="organisation")),
default=Wizard().step(AboutYouForm, name="about-you"),
)
.step(EmailForm, name="contact")
)
The only dependency is Django. Requires Python 3.10+ and Django 4.2+.
Installation
pip install django-gandalf # or: uv add django-gandalf
Gandalf ships no models or migrations, but it relies on standard Django
plumbing — the sessions app and middleware, and the request context
processor. Configuration has the exact
settings.
Documentation
The docs are in two halves, and you can start at either.
Learn is a walkthrough: one community grant application, built up a chapter at a time. Each chapter adds one idea, says why it exists, and leaves a runnable application behind. It deliberately does not cover every hook and every edge — read it start to finish the first time.
Reference is one page per thing —
Wizard, WizardViewSet, the summary, task lists, add another, storage, the
driver, the testing helpers — each with the complete API, worked usage, and
troubleshooting. Come here when you know what you are looking for.
| I want to… | Go to |
|---|---|
| build my first wizard | Learn, chapter 1 |
| see every builder method | Reference: Wizard |
| override a viewset hook | Reference: WizardViewSet |
| build a task list of wizards | Learn, chapter 12 · Reference: Task lists |
| test a wizard | Reference: Testing |
migrate from django-formtools |
Coming from formtools |
| know what replaying costs | Reference: Walk costs |
| drive a wizard from a script or an agent | Reference: Driver |
Every Learn chapter is real code under
tests/testapp/readme/, driven end to end by
tests/functional/test_readme_examples.py.
just serve runs them at http://127.0.0.1:8000/ so you can click through.
Contributing
See CONTRIBUTING.md for local setup, the separated unit
and functional test commands, and commit conventions.
ARCHITECTURE.md is the runtime-level view of how the
pieces fit; AGENT_ACCESS.md is the design behind the
driver and the agent.
1 maintainer
Metadata
1 maintainer
Release files for django-gandalf 0.23.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 | |
|---|---|---|---|
| django_gandalf-0.23.0.tar.gz | 414.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| django_gandalf-0.23.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 570.7 kB
Release files / django_gandalf-0.23.0.tar.gz
| Download URL | django_gandalf-0.23.0.tar.gz |
|---|---|
| Size | 414.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3981a8d944c9c4c263018f5e8bf55eaf99b2934f4f82549d19ac1604d430e2b
|
|
BLAKE2b-256 checksum How to use checksums |
ab1fce7064a98025fa2faaf30cda7b7e9e37e2b27d2bbf84ae01a4872780dddd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logRelease files / django_gandalf-0.23.0-py3-none-any.whl
| Download URL | django_gandalf-0.23.0-py3-none-any.whl |
|---|---|
| Size | 155.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1149cd1cac94d3bddde2dd33234449d941565706f7847b9a445c02273d5deba8
|
|
BLAKE2b-256 checksum How to use checksums |
ae46b0b3b3040b4d32112638ac5812f89b2779a574252de8d79568e280c69715
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency log
