Wagtail: the Django CMS where page models are Python classes

The problem Wagtail solves: page types as code, not as admin screens

Most CMS products ask you to assemble content types by clicking through an admin interface, then fight the result when the content model needs a migration. Wagtail inverts that. A page type is a Python class, its fields are Django fields, and the content model lives in your repository next to the templates that render it. The README describes the project as an open source content management system built on Django, focused on user experience, with precise control for designers and developers.

The audience follows from that. If your organisation already runs Django, Wagtail is an application you add to an existing project rather than a separate stack to operate. The README points readers with an existing Django project at the Wagtail Integration documentation, and points newcomers at the getting started tutorial. If nobody on the team writes Python, the setup path is a wall rather than a learning curve.

How the page tree, StreamField and Content API fit together

Wagtail's structural idea is the page tree. Pages are Django models that inherit from Wagtail's Page class and are ordered in a hierarchy, so URLs, navigation and permissions derive from position in that tree rather than from a separate routing table. The dependency list in pyproject.toml shows django-treebeard, the library that stores the hierarchy, and django-modelcluster, which lets a page hold draft revisions of related objects before they are committed. That pairing is why a draft page can have unsaved child content attached to it.

StreamField is the second mechanism. Instead of one rich-text blob, an editor composes a page from named block types that the developer declares in Python. The README says StreamField encourages flexible content without compromising structure, which is an accurate description of the trade-off: editors get freedom inside a vocabulary you define, and you get typed, queryable content instead of free-form HTML.

For decoupled front ends there is a Content API. The Makefile shows the project regenerating an OpenAPI snapshot at wagtail/api/v3/tests/snapshots/openapi.json, which tells you the v3 API is schema-described and its schema is checked in. Search is pluggable: the README lists Elasticsearch or PostgreSQL as backends, and pyproject.toml pins modelsearch, the abstraction layer over them.

The admin interface is not plain Django templates. package.json pins React 16 types, draft-js and Storybook, so parts of the editor are a JavaScript application with its own build step. That matters at upgrade time, which is covered below.

Installing Wagtail and publishing your first page

The README gives a start-to-running sequence for a new site. It assumes a virtual environment and Python 3. The wagtail start command scaffolds a project directory, and the generated requirements.txt is installed before any migration runs.

pip install wagtail
wagtail start mysite
cd mysite
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

After runserver, the development server is listening on Django's default port 8000. The admin lives at /admin/ on that host, and createsuperuser is what gives you an account to log in with. The README links the getting started tutorial for the detailed walkthrough beyond this point.

Compatibility is worth checking before you start, because it constrains the rest of your stack. The README states Wagtail supports Django 5.2.x, 6.0.x and 6.1.x, Python 3.11 through 3.14, and PostgreSQL, MySQL, MariaDB and SQLite with JSON1 as database backends. pyproject.toml sets requires-python to >=3.11 and lists Django>=5.2 as a dependency, so the packaging metadata and the README agree.

If you are adding Wagtail to a Django project that already exists, the README directs you to the integration documentation instead of the tutorial, and that is the correct order: the tutorial scaffolds a fresh project and will overwrite nothing, but it also will not show you how to attach the page tree to models you already have.

Where Wagtail is the wrong tool

The admin is not a no-code product. Defining a new content type means writing a model class, running makemigrations and migrate, and deploying. A marketing team that expects to add a content type on a Friday afternoon without a developer is better served by a system with a database-driven schema editor.

The front end is yours to build. Wagtail ships templates and a component library, but the README's claim of complete control over front-end design and structure is a statement of responsibility as much as a feature: there is no theme marketplace to fall back on, and no page will render correctly until you write the template. Teams without front-end capacity should price that in.

The JavaScript toolchain is a real operational cost. package.json requires Node >=24 and pins Storybook 10.2.4, React types at ^16.14.21 and draft-js types, while the Makefile's develop target runs npm install --no-save followed by npm run build. The setup.py sdist command shells out to npm run build when building a source distribution, and exits with an error if that fails. Anyone packaging Wagtail from source on a machine without Node, or from behind a registry that blocks the pinned packages, will hit that path. Installing the published wheel from PyPI avoids it, which is what the README's pip install wagtail does.

Draft and publish workflows are built in, but the README does not document rollback of a published page to a previous revision, so do not assume it exists without checking the editor documentation.

Wagtail compared with a Django admin and a headless CMS

The nearest alternative is Django's own admin. It is already there, requires no new dependency, and gives you CRUD screens over any model for free. What it does not give you is a page hierarchy with per-page permissions, a draft and publish workflow, a block-based content editor, image renditions or a content API. Building those on top of the Django admin is the work Wagtail has already done, and it is the reason to take the dependency rather than to avoid it.

The other comparison is a headless CMS such as a hosted content service. Those typically give you a schema editor, a CDN-backed delivery API and no servers to run. The difference in approach is where the content model lives. In a hosted headless CMS it lives in that vendor's database and is edited through their interface; in Wagtail it lives in your Python code and is edited through the admin you deploy. That makes Wagtail better when the content model and the application are the same product, and worse when you want to hand content modelling to people who do not deploy code. Wagtail does offer a Content API for decoupled front ends, so the API half of the headless pattern is available; the schema-editing half is not.

Releases, upgrades and what the BSD-3-Clause licence means here

Wagtail ships a feature release every three months, according to the README's release schedule section, and selected releases are designated Long Term Support, receiving maintenance updates for an extended period to address security and data-loss issues. The recent release list shows v8.0 on 2026-08-25, a release candidate v8.0rc2 a few days earlier, and a patch release v7.4.3 on 2026-08-20. The pattern is what matters for planning: quarterly features, and patch releases on the older line for teams that stay on LTS.

Upgrade cost is not zero even on LTS. The README's compatibility section warns that the details printed on GitHub may not reflect the current released version and points at the upgrading page in the documentation for the authoritative list. A jump between Django versions can require changes in your own project, and the release notes are where those are listed. Budget a maintenance window per upgrade rather than treating patch releases as free.

The licence is BSD-3-Clause, declared both in the README badge and in pyproject.toml, where license is set to BSD-3-Clause with license-files pointing at LICENSE. That is a permissive licence: it allows commercial use and modification, and it requires that the copyright notice and licence text be retained in redistributions. It does not include a patent grant, and it does not require you to publish your changes. This is a description of the licence text, not legal advice; if you are redistributing Wagtail inside a product, have your own counsel read LICENSE.

Editorial conclusion

Adopt Wagtail if your team already writes Django and wants editors working in a page tree you model yourself; skip it if you need a no-code install or a hosted SaaS with no Python deployment. Before committing, check the upgrade guide for the version you are on, confirm your database backend, and verify that a non-superuser can publish a page in a staging copy of your own content model.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. wagtail/wagtail on GitHub