Install & Compatibility
Where this runs
tested against v2.4.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 · 193.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.4s · import 0.000s · 191MB
195MB installed
● package 195MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ModelAdmin
✓ from wagtail_modeladmin.options import ModelAdmin
✗ from wagtail_modeladmin.options import ModelAdmin
Registers a Django model in the Wagtail admin sidebar.
from wagtail_modeladmin.options import ModelAdmin, modeladmin_register
from myapp.models import MyModel
class MyModelAdmin(ModelAdmin):
model = MyModel
menu_label = 'My Model'
menu_icon = 'pilcrow'
list_display = ('title', 'date')
search_fields = ('title',)
modeladmin_register(MyModelAdmin)
Debug
Known issues
breakingwagtail.contrib.modeladmin is removed in Wagtail 6.0. You must install wagtail-modeladmin and update imports.fixReplace `from wagtail.contrib.modeladmin...` with `from wagtail_modeladmin...`.
affects: Wagtail >=6.0
gotchamodeladmin_register is required (not just registering with @hooks like before). If you forget, the admin will not appear.fixCall `modeladmin_register(YourModelAdmin)` at module level in your wagtail_hooks.py.
affects: All
gotchaIf you are on Wagtail 5.2, you must use wagtail-modeladmin 1.x. Version 2.x requires Wagtail >=6.0.fixFor Wagtail 5.2, install wagtail-modeladmin==1.0.0 or compatible.
affects: wagtail-modeladmin >=2.0
deprecatedThe `form_fields_exclude` attribute is deprecated. Use `exclude_form_fields` instead.fixRename `form_fields_exclude` to `exclude_form_fields` in your ModelAdmin class.
affects: >=2.0
Upgrade
Version history
2.4.0latest on PyPI · released Jun 7, 2026
Audit
Dependencies
wagtailrequiredRequired peer dependency, version >=5.2