Notes

Replace Wagtail ModelAdmin with a ModelViewSet

Expose a small Django model in the Wagtail admin using the built-in ModelViewSet. Choose list columns, search fields and form fields explicitly.

Old Wagtail examples often import wagtail.contrib.modeladmin. That module was removed from Wagtail core in version 6. For a new interface to a plain Django model, use the built-in ModelViewSet. Existing projects with the external ModelAdmin package need a deliberate migration rather than a changed import alone.

This example uses a simple Brand model. It keeps the content model and admin registration separate, so fields and permissions are easy to see.

Define the model

In an installed application named catalog, create models.py:

from django.db import models


class Brand(models.Model):
    name = models.CharField(max_length=255)
    description = models.TextField(blank=True)
    logo = models.ForeignKey(
        "wagtailimages.Image",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
    )

    def __str__(self):
        return self.name

The string image reference avoids importing a concrete image class. If the project uses a custom Wagtail image model, use wagtail.images.get_image_model_string() for the relation instead. SET_NULL lets the brand survive deletion of its optional logo; related_name="+" avoids adding an unused reverse relation.

Generate and review the application’s migration before applying it. The admin registration does not create the database table.

Register the viewset

In catalog/wagtail_hooks.py:

from wagtail import hooks
from wagtail.admin.viewsets.model import ModelViewSet
from .models import Brand


class BrandViewSet(ModelViewSet):
    model = Brand
    icon = "tag"
    menu_label = "Brands"
    add_to_admin_menu = True
    list_display = ["name"]
    search_fields = ["name", "description"]
    form_fields = ["name", "description", "logo"]


@hooks.register("register_admin_viewset")
def register_brand_viewset():
    return BrandViewSet("brands")

Wagtail discovers wagtail_hooks.py in installed applications. The viewset name supplies its URL namespace; choose a unique name if the project has other registrations. form_fields is intentionally explicit: adding a model field later should not silently expose it to editors.

list_display controls the table columns and search_fields controls text search. Keep the list useful for identifying records before adding thumbnails, custom columns or more queries per row. If your content needs snippet features such as revisions and publishing, consider SnippetViewSet instead of treating this plain model screen as a publishing workflow.

Test the screen as an ordinary editor account as well as a superuser. Assign the model’s add, change, delete and view permissions according to the role; being able to enter Wagtail’s admin does not imply access to every model operation.

When migrating an existing ModelAdmin registration, remove the old registration only after checking menu duplication, URL changes, custom buttons, filters, form panels and any bookmarked links. Preserve the model and its data; changing the admin class does not require copying records.

Do not paste old Django-admin-style callable-column attributes into a viewset without checking its current column API. Start with real model fields, then introduce custom presentation only when the screen needs it.

The official generic-view guide and ModelViewSet reference describe current extension points. Wagtail’s 6.0 release notes explain the ModelAdmin removal.