Wagtail ModelAdmin

2.3.0 verified Mon Apr 27 auth: no python

Add any model in your project to the Wagtail admin with full CRUD and customisation. Formerly part of Wagtail core as `wagtail.contrib.modeladmin`. Version 2.3.0 (latest) supports Wagtail 6.x and Python >=3.10. Release cadence is irregular, roughly every 6-12 months.

pip install wagtail-modeladmin

Common errors

error ModelAdmin class not found: 'ModelAdmin' is not defined ↓

cause Import from the wrong module (wagtail.contrib.modeladmin).

fix

Change to from wagtail_modeladmin.options import ModelAdmin.

error ImportError: cannot import name 'ModelAdmin' from 'wagtail_modeladmin' (unknown location) ↓

cause The package is not installed or import path is wrong.

fix

Install with pip install wagtail-modeladmin and use from wagtail_modeladmin.options import ModelAdmin.

error AttributeError: 'MyModelAdmin' object has no attribute 'get_app_label_from_model_name' ↓

cause Internal API change in version 2.x. Method removed.

fix

Override get_menu_label() or get_menu_icon() directly; avoid using removed internal methods.

error TypeError: __init__() got an unexpected keyword argument 'style_prefix' ↓

cause Styling API changed between major versions.

fix

Remove the style_prefix argument. Use menu_icon and CSS customisation via extra_css.

Warnings

breaking wagtail.contrib.modeladmin is removed in Wagtail 6.0. You must install wagtail-modeladmin and update imports. ↓

fix Replace `from wagtail.contrib.modeladmin...` with `from wagtail_modeladmin...`.

gotcha modeladmin_register is required (not just registering with @hooks like before). If you forget, the admin will not appear. ↓

fix Call `modeladmin_register(YourModelAdmin)` at module level in your wagtail_hooks.py.

gotcha If you are on Wagtail 5.2, you must use wagtail-modeladmin 1.x. Version 2.x requires Wagtail >=6.0. ↓

fix For Wagtail 5.2, install wagtail-modeladmin==1.0.0 or compatible.

deprecated The `form_fields_exclude` attribute is deprecated. Use `exclude_form_fields` instead. ↓

fix Rename `form_fields_exclude` to `exclude_form_fields` in your ModelAdmin class.

Imports

ModelAdmin
wrong
```
from wagtail.contrib.modeladmin.options import ModelAdmin
```
correct
```
from wagtail_modeladmin.options import ModelAdmin
```
wagtail.contrib.modeladmin was removed in Wagtail 6.0. Use this standalone package instead.

ModelAdminGroup

from wagtail_modeladmin.options import ModelAdminGroup

InspectorPanel

from wagtail_modeladmin.views import InspectorPanel

Quickstart

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)