Template Tags

Encode UUIDs as display IDs directly in Django templates.

Setup

Add django_display_ids to your INSTALLED_APPS:

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

Then load the template library in your templates:

{% load display_ids %}

Filter: display_id

Encode a UUID as a display ID:

{% load display_ids %}

{{ some_uuid|display_id:"inv" }}
{# Output: inv_2aUyqjCzEIiEcYMKj7TZtw #}

{# With a model's UUID field #}
{{ invoice.id|display_id:"inv" }}

{# Foreign key UUID #}
{{ order.customer_id|display_id:"cust" }}

The prefix argument is required and must be 1-16 lowercase letters.

Note

For models with DisplayIDModel, use the display_id property directly:

{{ invoice.display_id }}

The filter is for encoding raw UUIDs that don’t come from a mixin-enabled model.

Error Handling

Errors raise TemplateSyntaxError:

• Value is not a UUID

• Invalid prefix format (must be 1-16 lowercase letters)

None values return an empty string (not an error).

Examples

Encoding foreign key UUIDs:

{% load display_ids %}

<p>Customer: {{ order.customer_id|display_id:"cust" }}</p>
<p>Invoice: {{ payment.invoice_id|display_id:"inv" }}</p>

Building URLs with display IDs:

{% load display_ids %}

<a href="/customers/{{ customer.id|display_id:"cust" }}/">
    View Customer
</a>

Loop over UUIDs:

{% load display_ids %}

{% for uuid in related_ids %}
    <li>{{ uuid|display_id:"rel" }}</li>
{% endfor %}