django-display-ids 0.7.0

Stripe-like prefixed IDs for Django. Works with existing UUIDs — no schema changes.

django-display-ids

Stripe-like prefixed IDs for Django. Works with existing UUIDs — no schema changes.

Why?

UUIDv7 (native in Python 3.14+) offers excellent database performance with time-ordered indexing. But they lack context — seeing 550e8400-e29b-41d4-a716-446655440000 in a URL or log doesn't tell you what kind of object it refers to.

Display IDs like inv_2aUyqjCzEIiEcYMKj7TZtw are more useful: the prefix identifies the object type at a glance, and they're compact and URL-safe. But storing display IDs in the database is far less efficient than native UUIDs.

Different consumers have different needs:

• Humans prefer slugs (my-invoice) or display IDs (inv_xxx)
• APIs and integrations work well with UUIDs

This library gives you the best of both worlds: accept any format in your URLs and API endpoints, then translate to an efficient UUID lookup in the database. Store UUIDs, expose whatever format your users need.

Installation

pip install django-display-ids

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_display_ids",
]

Quick Start

Add the mixin to your model:

# models.py

import uuid
from django.db import models
from django_display_ids import DisplayIDModel

class Invoice(DisplayIDModel, models.Model):
    display_id_prefix = "inv"
    uuid_field = "uuid"
    uuid = models.UUIDField(default=uuid.uuid7, unique=True)
    slug = models.SlugField(unique=True)

Update your URLconf:

# urls.py

from django.urls import path, register_converter
from django_display_ids import DisplayIDOrUUIDOrSlugConverter

register_converter(DisplayIDOrUUIDOrSlugConverter, "identifier")

urlpatterns = [
    path("invoices/<identifier:id>/", InvoiceDetailView.as_view()),
]

Add the mixin to your view:

# views.py

# Django CBV
from django.views.generic import DetailView
from django_display_ids import DisplayIDMixin

class InvoiceDetailView(DisplayIDMixin, DetailView):
    model = Invoice
    lookup_param = "id"

# Django REST Framework
from rest_framework.viewsets import ModelViewSet
from django_display_ids.contrib.rest_framework import DisplayIDMixin

class InvoiceViewSet(DisplayIDMixin, ModelViewSet):
    queryset = Invoice.objects.all()
    serializer_class = InvoiceSerializer
    lookup_url_kwarg = "id"

Your views now accept:

• inv_2aUyqjCzEIiEcYMKj7TZtw (display ID)
• 550e8400-e29b-41d4-a716-446655440000 (UUID)
• my-invoice (slug)

Update your templates:

{% load display_ids %}

{{ invoice.display_id }}                       {# inv_2aUyqjCzEIiEcYMKj7TZtw #}
{{ order.customer_id|display_id:"cust" }}      {# encode any UUID #}

Features

• Multiple identifier formats: display ID (prefix_base62uuid), UUID (v4/v7), slug
• Framework support: Django CBVs and Django REST Framework
• Template filter: Encode UUIDs as display IDs in templates
• Zero model changes required: Works with any existing UUID field
• OpenAPI integration: Automatic schema generation with drf-spectacular

Documentation

Full documentation at django-display-ids.readthedocs.io.

Contributing

See CONTRIBUTING.md.

Related Projects

If you need ID generation and storage (custom model fields), consider:

• django-prefix-id — PrefixIDField that generates and stores base62-encoded UUIDs
• django-spicy-id — Drop-in AutoField replacement
• django-charid-field — CharField wrapper supporting cuid, ksuid, ulid

django-display-ids works with existing UUID fields and handles resolution only — no migrations required.