{"id":2355,"library":"wagtail","title":"Wagtail CMS","description":"Wagtail is an open-source content management system (CMS) built on the Django framework, known for its intuitive content editing interface and flexible development architecture. It is currently at version 7.3.1 and follows a regular release cadence with major versions typically released annually, accompanied by frequent patch and minor releases addressing bug fixes and security updates.","status":"active","version":"7.3.1","language":"en","source_language":"en","source_url":"https://github.com/wagtail/wagtail","tags":["django","cms","content management","web development","admin"],"install":[{"cmd":"pip install wagtail","lang":"bash","label":"Install Wagtail"}],"dependencies":[{"reason":"Wagtail is built on the Django framework.","package":"Django","optional":false},{"reason":"Required for image processing within Wagtail.","package":"Pillow","optional":false}],"imports":[{"note":"The `wagtail.core` module was deprecated and removed in Wagtail 3.0+. Core models moved to `wagtail.models`.","wrong":"from wagtail.core.models import Page","symbol":"Page","correct":"from wagtail.models import Page"},{"note":"The `wagtail.core` module was deprecated and removed in Wagtail 3.0+. Core fields moved to `wagtail.fields`.","wrong":"from wagtail.core.fields import StreamField","symbol":"StreamField","correct":"from wagtail.fields import StreamField"},{"note":"The primary way to import Wagtail's built-in block types (e.g., `blocks.CharBlock`).","symbol":"blocks","correct":"from wagtail import blocks"},{"note":"The `edit_handlers` module was removed and replaced by `wagtail.admin.panels` in Wagtail 3.0+.","wrong":"from wagtail.admin.edit_handlers import FieldPanel","symbol":"FieldPanel","correct":"from wagtail.admin.panels import FieldPanel"}],"quickstart":{"code":"from django.db import models\nfrom wagtail.models import Page\nfrom wagtail.fields import StreamField\nfrom wagtail import blocks\nfrom wagtail.admin.panels import FieldPanel\n\nclass HomePage(Page):\n    \"\"\"\n    A simple example of a Wagtail Page model with a StreamField.\n    This defines a flexible content structure editable in the Wagtail admin.\n    \"\"\"\n    body = StreamField([\n        ('heading', blocks.CharBlock(form_classname=\"full title\")), # Simple text block\n        ('paragraph', blocks.RichTextBlock()),                      # Rich text editor\n        ('image', blocks.ImageChooserBlock()),                     # Image picker\n        ('embed', blocks.RawHTMLBlock(icon='code')),               # Raw HTML embed\n    ], use_json_field=True, blank=True, null=True)\n\n    # Define the fields that will appear in the Wagtail admin editor\n    content_panels = Page.content_panels + [\n        FieldPanel('body'),\n    ]\n\n    # You would typically also define a template (e.g., home/home_page.html)\n    # and potentially an `abstract` page for common fields across your site.\n","lang":"python","description":"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."},"warnings":[{"fix":"Update 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`.","message":"The `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.","severity":"breaking","affected_versions":"3.0+"},{"fix":"Update 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.","message":"The `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.","severity":"breaking","affected_versions":"3.0+"},{"fix":"Always 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.","message":"For `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.","severity":"breaking","affected_versions":"3.0+"},{"fix":"Before 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).","message":"Wagtail 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.","severity":"gotcha","affected_versions":"All versions, critical during upgrades."},{"fix":"Refer 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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions when customising StreamField rendering."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}