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
Workflow operations over the API for pages and snippets using
WorkflowMixinMore 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_ofMore valid Markdown in v3 API rich text
markdownoutput for styled text around links, line breaks, multi-paragraph quotes and nested listsSkipping API setup and schema generation on startup when
wagtail.api.v3is not installedRespect 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_SIZEparameter to Cloudflare backend to control number of URLs sent per purge request (Kevin Howbrook)Add
HTMLToMarkdownConverterto convert arbitrary HTML (such as rendered pages) to Markdown (Albina Starykova)Add optional
rootparameter toqueryControllerandqueryControllerAllto scope Stimulus controller lookups to an element (Roee Sivan)
Bug fixes¶
Avoid redundant writes back to the cache on
get_renditionandget_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_headerto 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_forandexplorable_instancesinPagePermissionPolicy(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
SuspiciousOperationrather thanAttributeError(Matt Westcott)Prevent syntax errors from crashing a dev server with a
RuntimeErrorwhen using Jinja2 (Sage Abdullah, Matt Westcott)Add
Vary: X-Requested-Withto responses from pages with anajax_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
MAILERSsetting 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_renditionscommand 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_L10Nsetting (DresdenGman)Squash testapp migrations (Sage Abdullah)
Use
format_htmlfor 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
MAILERSsetting (Sage Abdullah)Use
MAILERSon 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.