Django Admin

Enable searching by display ID or raw UUID in the Django admin.

DisplayIDAdminSearchMixin

from django.contrib import admin
from django_display_ids import DisplayIDAdminSearchMixin

@admin.register(Invoice)
class InvoiceAdmin(DisplayIDAdminSearchMixin, admin.ModelAdmin):
    list_display = ["id", "display_id", "name", "created"]
    search_fields = ["name"]  # display ID and UUID search is automatic

Now you can search by display ID or raw UUID in the admin search box:

• inv_2aUyqjCzEIiEcYMKj7TZtw (display ID)

• 01970b3e-1234-5678-9abc-def012345678 (UUID with hyphens)

• 01970b3e123456789abcdef012345678 (UUID without hyphens)

How It Works

The mixin intercepts search queries and checks if they look like a display ID (contain an underscore) or a raw UUID. If so, it decodes the display ID or parses the UUID and does an exact match against the UUID field. Otherwise, it falls back to the standard search_fields behavior.

This means your existing text-based searches continue to work alongside display ID and UUID searches.

Configuration

The mixin automatically detects the UUID field: first from your model’s uuid_field attribute (if using DisplayIDModel), then from the DISPLAY_IDS["UUID_FIELD"] setting, then "id".

Override with:

class InvoiceAdmin(DisplayIDAdminSearchMixin, admin.ModelAdmin):
    uuid_field = "uuid"  # custom UUID field name

Searching Related UUID Fields

To search by a related model’s display ID or UUID (e.g., find all sessions belonging to a user), override get_search_results and use the _parse_identifier static method:

@admin.register(Session)
class SessionAdmin(DisplayIDAdminSearchMixin, admin.ModelAdmin):
    search_fields = ["name"]

    def get_search_results(self, request, queryset, search_term):
        original_queryset = queryset
        queryset, use_distinct = super().get_search_results(
            request, queryset, search_term
        )
        # Search the related user's UUID field too
        if uuid_val := self._parse_identifier(search_term):
            queryset |= original_queryset.filter(
                user__uid=uuid_val
            )
        return queryset, use_distinct

Now searching by user_2aUyqjCzEIi... or a raw UUID will also match sessions belonging to that user.

_parse_identifier is a static method that tries to decode a display ID first, then falls back to raw UUID parsing. It returns None for unparseable input and never raises exceptions.

Displaying Display IDs

If your model uses DisplayIDModel, you can include display_id in list_display:

class Invoice(DisplayIDModel, models.Model):
    display_id_prefix = "inv"
    # ...

@admin.register(Invoice)
class InvoiceAdmin(DisplayIDAdminSearchMixin, admin.ModelAdmin):
    list_display = ["id", "display_id", "name"]  # display_id is a property