Install & Compatibility
Where this runs
tested against v4.5.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 · 242.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 12.6s · import 0.000s · 238MB
238MB installed
● package 238MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PageFactory
✓ from wagtail_factories import PageFactory
✗ from wagtail_factories import PageFactory
This quickstart demonstrates how to define a Wagtail page model with a StreamField and then create corresponding `wagtail-factories` for both the page and its StreamField blocks. It uses `StreamFieldFactory` to populate StreamField content and shows how to define factories for specific block types like `CharBlock`. The example highlights the use of `factory.Faker` for realistic data and `factory.Sequence` for unique titles, and notes that execution requires a Django/Wagtail environment.
import factory
from django.db import models
from wagtail.models import Page
from wagtail.fields import RichTextField, StreamField
from wagtail import blocks
from wagtail_factories import PageFactory, StreamFieldFactory
from wagtail_factories.blocks import CharBlockFactory
# Define a simple Wagtail Page model
class MyPage(Page):
body = RichTextField(blank=True)
content = StreamField([
('heading', blocks.CharBlock(form_classname='full title')),
('paragraph', blocks.RichTextBlock()),
], use_json_field=True, blank=True)
content_panels = Page.content_panels # Simplified for example
# Define factories for the model and its StreamField blocks
class HeadingBlockFactory(CharBlockFactory):
class Meta:
model = blocks.CharBlock # For CharBlockFactory itself
class MyPageFactory(PageFactory):
class Meta:
model = MyPage
title = factory.Sequence(lambda n: f'Test Page {n}')
body = factory.Faker('text')
content = StreamFieldFactory({
'heading': HeadingBlockFactory,
'paragraph': StreamFieldFactory._do_nothing, # For simple blocks or when default behavior is fine
})
# Example usage (requires Django environment setup)
# To run this code, you'd typically need a Django project configured with Wagtail.
# For testing purposes, you might use Django's test client or a custom setup.
if __name__ == '__main__':
print("This quickstart demonstrates factory definition. To create instances, run within a configured Django/Wagtail project.")
print("Example: `page = MyPageFactory()` would create a page in your database.")
# Example of creating a page (would run within a Django test or shell):
# from django.test import TestCase
# class MyTest(TestCase):
# def test_page_creation(self):
# page = MyPageFactory()
# self.assertIsNotNone(page.pk)
# print(f"Created page: {page.title}")
# print(f"StreamField content keys: {[b.block_type for b in page.content]}")
Debug
Known issues
breakingWagtail Factories releases are tightly coupled to Wagtail versions. Upgrading `wagtail` often requires a corresponding upgrade of `wagtail-factories`. For example, v4.1.0 dropped support for Wagtail < 4.1, and v4.4.0 added support for Wagtail 7.fixAlways check the `wagtail-factories` release notes and README for compatible Wagtail versions before upgrading either library. Ensure your `wagtail-factories` version supports your `wagtail` version.
affects: All versions, especially major upgrades
breakingThe usage of `StreamFieldFactory` was significantly changed in v3.0.0 with the introduction of `StreamBlockFactory`. Prior to this, `StreamFieldFactory` might have handled nested blocks implicitly, but now explicit block factories (e.g., `CharBlockFactory`, `ImageBlockFactory`) or `StreamFieldFactory._do_nothing` are often required for specific block types.fixReview your `StreamFieldFactory` definitions when upgrading from versions older than 3.0.0. You will likely need to explicitly define factories for individual StreamBlocks or use `StreamFieldFactory._do_nothing` for blocks where default behavior is desired. Consult the official documentation for updated `StreamFieldFactory` usage.
affects: <3.0.0
breakingIn v4.0.0, `ListBlockFactory` changed its return type for Wagtail versions >= 2.16 from a plain Python `list` to a `wagtail.blocks.list_block.ListValue`. This could affect existing code that expects a standard `list` object.fixUpdate any code that interacts with the output of `ListBlockFactory` to correctly handle `wagtail.blocks.list_block.ListValue` objects, which behave similarly to lists but are not identical.
affects: >=4.0.0 on Wagtail >= 2.16
breakingDependency on `factory_boy` has evolved. `wagtail-factories` v2.0.1 required `factory_boy>=3.0`, and v2.1.0 further required `factory_boy>=3.2`. Using an older `factory_boy` version will lead to compatibility errors.fixEnsure `factory_boy` is installed at a compatible version. For recent `wagtail-factories` versions (e.g., 4.x), `factory_boy>=3.2` is generally required. Consult `pyproject.toml` or `setup.py` for exact dependency ranges if issues arise.
affects: <2.1.0
Upgrade
Version history
4.5.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
wagtailrequiredCore functionality is tied to Wagtail. Ensure `wagtail-factories` version matches your `wagtail` version for compatibility.
factory_boyrequiredThe library is built on top of `factory_boy` for generating model instances.