Wagtail 8.1 release notes

November 2, 2026

What’s new

Wagtail Space 2026

Our flagship Wagtail Space conference returns! Coming up 18-20 November, a free virtual event for people who are improving the world through code and content. 22 presentations over two days of talks and one day of community events. Register to join us 🚀

Python 3.15 support

This release adds formal support for Python 3.15. See the list of compatible versions of Python.

Varying page responses

Wagtail can now serve more than one representation of a page at the same URL, chosen per request from the Accept header. This general-purpose capability can be used to render JSON responses for API clients, Markdown for AI agents as a form of agent readiness. This can also be set up with any other format.

See How to vary page responses for full details. This feature was developed by Albina Starykova.

API v3 improvements

We have made several improvements to the v3 API preview, including support for:

  • TypedTableBlock in v3 API write requests

  • Nested inline relations in the API write requests

  • ImageRenditionField for v3 API

  • Workflow operations over the API for pages and snippets using WorkflowMixin

  • StreamField block schemas

  • More API schema details for ForeignKey, ManyToManyField, GenericRelation, and Redirects

  • Improved handling of ForeignKey schema generation for multi-level relations, multi-table inheritance, and self-references

  • Correct handling of references outside of the result set criteria for the filters ancestor_of, child_of, descendant_of, translation_of

  • More valid Markdown in v3 API rich text markdown output for styled text around links, line breaks, multi-paragraph quotes and nested lists

  • Skipping API setup and schema generation on startup when wagtail.api.v3 is not installed

  • Respect page tree ordering in listings endpoint by default

  • More optimized OpenAPI schema for projects with a large number of models

Those features were implemented by Sage Abdullah, Thibaud Colas, Satyam Laheri, Albina Starykova.

Prototype Wagtail CLI

As part of the new v3 API preview, we are introducing a prototype Wagtail CLI to speed up and automate common operations on Wagtail projects. This command line interface currently supports interacting with live sites via the API, searching developer docs, loading agent skills, and scaffolding new projects.

For more information, read Prototyping a new CLI for Wagtail. This feature was implemented by Thibaud Colas and Sage Abdullah.

Official agent skills

We now provide official agent skills for developers, that work together with the CLI and the API. They make coding agents work more effectively on Wagtail-related development tasks.

This feature was implemented by Thibaud Colas.

SEO power tools: page metadata

Content checks now show the page’s meta titles and descriptions, with their lengths measured per SEO recommendations based on typical search engine display budgets. This is shown in the Checks panel of the page editor, and in the Checks dialog of the userbar. Editors can also expand “View more meta tags” to inspect all of the page’s SEO-relevant meta tags.

This feature was developed by Thibaud Colas, with SEO guidance from Beth Parnell. We would like to thank Freedom of the Press Foundation for their sponsorship of this feature.

Multilingual, faster sitemaps

This release improves the handling of sitemaps for multilingual sites, and documents how to set up caching for sitemaps.

  • Add alternate links to sitemap for translated pages

  • Include pages from all locales in the sitemap when internationalisation is enabled, including pages with no live, public version in the site root page’s locale

  • Document how to cache the sitemap

  • Prevent error when accessing the sitemap via an unknown host and no default site is configured

Thank you to contributors Julie Rymer, Jawad Khan, and Albina Starykova for implementing those improvements. And to Beth Parnell for SEO guidance.

Other features

  • Only auto-create redirects when moving or renaming live pages, not draft; use WAGTAILREDIRECTS_AUTO_CREATE = 'always' to restore previous behaviour (Sage Abdullah)

  • Show allowed file types as part of document upload form help text (Bhavesh Sharma)

  • Purge frontend cache when a page is moved or its slug is changed (Jake Howard)

  • Add PURGE_BATCH_SIZE parameter to Cloudflare backend to control number of URLs sent per purge request (Kevin Howbrook)

  • Add HTMLToMarkdownConverter to convert arbitrary HTML (such as rendered pages) to Markdown (Albina Starykova)

  • Add optional root parameter to queryController and queryControllerAll to scope Stimulus controller lookups to an element (Roee Sivan)

Bug fixes

  • Avoid redundant writes back to the cache on get_rendition and get_renditions (Mason Lyons, Matt Westcott)

  • Allow ChooserBlock.bulk_to_python() to resolve records with primary keys that need converting to their native type, such as UUIDs (Saksham Chawla)

  • Fix excessive memory usage when copying a page with many revisions (Taras Panasiuk)

  • Prevent nested submenu labels from becoming invisible when using the slim sidebar (Neda Gilanian, Sage Abdullah)

  • Prevent memory exhaustion through over-long inputs to get_supported_content_language_variant (Matt Westcott)

  • Use add_unredirected_header to pass authorization headers to Facebook/Instagram embed APIs (Matt Westcott)

  • Prevent failures when instantiating form pages within migrations (Satyam Laheri)

  • Fix audit log actions for copy, copy-for-translation and create-alias to log the page being copied rather than its parent (Waqas Ahmed)

  • Respect EXIF orientation on avatar uploads (Damien Meur)

  • Improve performance of instances_user_has_any_permission_for and explorable_instances in PagePermissionPolicy (Ayush Kumar)

  • Prevent bulk deletion of automatically-created redirects when a slug change does not change the page URL (Sage Abdullah)

  • Ensure signature check failure on redirect import raises SuspiciousOperation rather than AttributeError (Matt Westcott)

  • Prevent syntax errors from crashing a dev server with a RuntimeError when using Jinja2 (Sage Abdullah, Matt Westcott)

  • Add Vary: X-Requested-With to responses from pages with an ajax_template (Albina Starykova)

  • Protect workflow action buttons against multiple submissions that could cause a crash or an overwrite (Nick Moreton, Jakub Mastalerz, Sage Abdullah)

  • Reject workflow actions if the current task state does not match what the user submitted (Sage Abdullah)

  • Prevent N+1 queries in Site.get_site_root_paths() when internationalization is enabled (Andy Babic)

  • Use credentials configured in the MAILERS setting on Django 6.1 when sending form submission emails (Maarten Ureel)

Documentation

  • Fix broken links to Cloudflare and Handsontable documentation (Roshan Ramani)

  • Update generative AI policy to require pull request descriptions to be human-written (Matt Westcott)

  • Fix documentation for the wagtail_update_image_renditions command to correctly describe behaviour around purging of renditions (Saksham Chawla)

  • Add signpost to generative AI policy in contributing guidelines and issue templates (Matt Westcott)

Maintenance

  • Drop support for Python 3.10

  • Remove obsolete use of USE_L10N setting (DresdenGman)

  • Squash testapp migrations (Sage Abdullah)

  • Use format_html for submit translation form help text (Keerthi Kumar)

  • Add testing section to PR template (Srishti Jaiswal)

  • Remove jQuery usage in ExpandingFormset (Keerthi Kumar)

  • Rewrite page privacy ancestor link formatting to verify XSS safety (Keerthi Kumar, Matt Westcott)

  • Ensure ‘parent’ can be translated correctly in different contexts (Storm Heg)

  • Update project template to use Django 6.1’s MAILERS setting (Sage Abdullah)

  • Use MAILERS on Django 6.1+ when sending emails to avoid deprecation warnings (Sage Abdullah)

Upgrade considerations - changes affecting all projects

Pages with an ajax_template now vary on X-Requested-With

Responses from a page that defines an ajax_template now include Vary: X-Requested-With, so that caches store the AJAX fragment and the full page separately. Previously the two could be cached under the same key, and a cache could serve the fragment to a normal browser request (or the full page to an AJAX request). Shared caches that honour Vary will now hold one extra entry per such page, so cache size and hit ratios may change. See How to vary page responses for details.

Sitemaps include pages from all locales

When WAGTAIL_I18N_ENABLED is True, the sitemap now includes pages from the page trees of all locales of the site. Previously, only pages in the site root page’s locale were listed. Sitemaps of multilingual sites may now contain more entries. See Multi-language support for details.

Upgrade considerations - deprecation of old functionality

Removed support for Python 3.10

Python 3.10 is no longer supported as of this release; please upgrade to Python 3.11 or above before upgrading Wagtail.

Upcoming deprecation of the v2 API

The v2 API is planned for deprecation in favor of the v3 API. It remains available and supported in this release, with no changes. From Wagtail 8.2, using the built-in v2 API will raise deprecation warnings, to be removed from Wagtail in version 9.0. It will also be published as a separate package for those who would like to keep using it. See the deprecation timeline and Migrating from the v2 API to plan your migration, and share your feedback on how to improve the new API and migration process.

Upgrade considerations - changes to undocumented internals

Internal admin API has been replaced

The internal API used by the admin interface’s page explorer, previously available at /admin/api/main/, has been replaced with a minimal API built on the same foundations as the v3 API. The new API only provides a single endpoint for the page explorer at /admin/api/explorer/<id>/. The page listing, detail, and actions endpoints (e.g. /admin/api/main/pages/<id>/action/publish/) and the construct_admin_api hook have been removed. If you were relying on these, consider using the v3 API instead.