Install & Compatibility
Where this runs
tested against v8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 216.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 11.1s · import 0.000s · 212MB
213MB installed
● package 213MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Page
✓ from wagtail.models import Page
✗ from wagtail.models import Page
This code snippet demonstrates a basic Wagtail `Page` model with a `StreamField`. The `StreamField` allows content editors to dynamically add and reorder various content blocks (like headings, paragraphs, images, and embeds) on a page. This model should be placed in `models.py` within a Django app of your Wagtail project, then migrate and set up a superuser to access the Wagtail admin.
from django.db import models
from wagtail.models import Page
from wagtail.fields import StreamField
from wagtail import blocks
from wagtail.admin.panels import FieldPanel
class HomePage(Page):
"""
A simple example of a Wagtail Page model with a StreamField.
This defines a flexible content structure editable in the Wagtail admin.
"""
body = StreamField([
('heading', blocks.CharBlock(form_classname="full title")), # Simple text block
('paragraph', blocks.RichTextBlock()), # Rich text editor
('image', blocks.ImageChooserBlock()), # Image picker
('embed', blocks.RawHTMLBlock(icon='code')), # Raw HTML embed
], use_json_field=True, blank=True, null=True)
# Define the fields that will appear in the Wagtail admin editor
content_panels = Page.content_panels + [
FieldPanel('body'),
]
# You would typically also define a template (e.g., home/home_page.html)
# and potentially an `abstract` page for common fields across your site.
wagtail --version
Debug
Known issues
breakingThe `wagtail.core` module was deprecated and removed in Wagtail 3.0+. Core components like `Page`, `Site`, `StreamField`, and `Image` were moved to more specific modules.fixUpdate all import paths. For example, change `from wagtail.core.models import Page` to `from wagtail.models import Page`, and `from wagtail.core.fields import StreamField` to `from wagtail.fields import StreamField`.
affects: 3.0+
breakingThe `wagtail.admin.edit_handlers` module was removed and replaced by `wagtail.admin.panels` in Wagtail 3.0+. Panel classes (`FieldPanel`, `MultiFieldPanel`, etc.) and their API have changed significantly.fixUpdate import paths from `wagtail.admin.edit_handlers` to `wagtail.admin.panels` and refactor panel definitions according to the new API. Consult the Wagtail 3.0+ upgrade guide for detailed changes.
affects: 3.0+
breakingFor `StreamField` definitions, `use_json_field=True` is now the default and implicitly required for new fields in Wagtail 3.0+. Projects upgrading from older versions where `StreamField` might have used a different underlying storage may require manual data migrations.fixAlways include `use_json_field=True` for new `StreamField` definitions for clarity. Review the official Wagtail upgrade guides for detailed data migration strategies if upgrading an existing project with `StreamField`s.
affects: 3.0+
gotchaWagtail has strict requirements on the supported Django versions for each major release. Using an unsupported Django version will lead to integration issues, runtime errors, or unexpected behavior.fixBefore upgrading Wagtail or Django, always consult the official Wagtail documentation for the compatibility matrix for your specific Wagtail version (e.g., Wagtail 7.x requires Django 4.2 to 6.0).
affects: All versions, critical during upgrades.
gotchaWhen rendering `StreamField` content in templates, ensure you correctly use Wagtail's template tags like `{% include_block %}` or `{{ self.body|richtext }}`. Custom block templates need careful setup, and direct iteration over `StreamField` values may not provide the full block context for rich rendering.fixRefer to Wagtail's StreamField template documentation for best practices. Use `{% include_block %}` with appropriate block templates for complex blocks, and ensure custom block rendering logic handles `self` and `parent_context` correctly. affects: All versions when customising StreamField rendering.
Upgrade
Version history
8.0latest on PyPI · released Aug 25, 2026
Audit
Dependencies
DjangorequiredWagtail is built on the Django framework.
PillowrequiredRequired for image processing within Wagtail.