Guide

How to Customize Django Admin Without Rebuilding It

8 min read

A practical path for customizing Django admin, from ModelAdmin options and CSS variables to template overrides, including what Django 6.1 changed and when a theme is the easier choice.

You can change a lot in Django admin without rebuilding it. The trick is to pick the smallest change that does the job, and only move up a step when it can't. Each step gives you more control, but it also gives you more to look after every time Django updates.

Here is the ladder I would climb, from lightest to heaviest:

What you wantUse thisUpkeep
Different columns, filters, search, or actionsModelAdmin optionsVery low
A new name and titles for the adminAdminSite attributesVery low
Your own colorsCSS variables in an admin/base.html overrideLow
A new button or section on a pageOverride one template blockMedium
A new screen inside the adminA custom view with get_urls()Medium
A complete new look and layoutA themeDepends on who maintains it

Most projects never need to go past the middle of that table.

Start with ModelAdmin options

Before you touch a template, check whether a ModelAdmin option already does what you want. Most day-to-day complaints about the admin, like "I can't find anything" or "I can't see the field I care about", are solved here. Nothing in this step depends on how Django draws the page, so it survives upgrades well.

from django.contrib import admin

from .models import Order


@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
    list_display = ["reference", "customer", "status", "created_at"]
    list_filter = ["status", "created_at"]
    search_fields = ["reference", "customer__email"]
    date_hierarchy = "created_at"
    readonly_fields = ["created_at"]
A change list with the columns, filters, and search people actually use

Django 6.1 gives this step a small bonus. When list_select_related is left at its default, the change list now only loads the related objects named in list_display, instead of every foreign key on the model. Setting list_select_related = True is deprecated in 6.1, so name the fields you need instead.

Django 6.1 also lets an admin action appear on the edit page, not only on the list. That is a nice way to put a "Mark as shipped" button where people are already looking at the order:

from django.contrib import admin
from django.contrib.admin import ActionLocation


@admin.action(
    location=[ActionLocation.CHANGE_FORM, ActionLocation.CHANGE_LIST],
    description="Mark as shipped",
    description_plural="Mark selected orders as shipped",
)
def mark_shipped(modeladmin, request, queryset):
    queryset.update(status="shipped")


class OrderAdmin(admin.ModelAdmin):
    actions = [mark_shipped]
One action, available on both the list and the edit page (Django 6.1 and later)

Rename the admin and change its titles

The next lightest change is the text. By default the admin says "Django administration" at the top and "Django site admin" in the browser tab. Three attributes on the admin site change that, and a fourth removes the "View site" link if you don't want it.

from django.contrib import admin

admin.site.site_header = "Acme back office"
admin.site.site_title = "Acme admin"
admin.site.index_title = "Welcome back"
# admin.site.site_url = None  # hides the "View site" link
Put this in an admin.py or your project's urls.py

That is five minutes of work, and your team will feel the difference right away. It also tells people they are in your product's admin, not a generic one.

Change colors with CSS variables

You don't need to write a stylesheet that fights Django. The admin keeps its colors and fonts in CSS variables, so you can change a handful of values and the whole admin follows. Django's own documentation shows this as a template override of admin/base.html that adds a style block:

{% extends 'admin/base.html' %}
{% block extrastyle %}{{ block.super }}
<style>
html[data-theme="light"], :root {
  --primary: #9774d5;
  --secondary: #785cab;
  --link-fg: #7c449b;
  --link-selected-fg: #8f5bb2;
}
</style>
{% endblock %}
Save as templates/admin/base.html in your project (these colors are Django's own purple example)

The file goes in a templates folder that your TEMPLATES setting lists under DIRS, inside an admin folder. If you have customized the template loaders, keep the filesystem loader ahead of the app directories loader, or Django will find its own copy first.

Remember dark mode. The dark colors live in a separate file in Django (dark_mode.css), so a color change that looks right in light mode can look odd in dark mode. Open both before you call it done.

Override one template block, not the whole page

Sometimes a color isn't enough and you want to add something, like a link next to the History button. It is tempting to copy the whole template and edit it. Django's documentation advises against that: replacing a whole admin template is usually neither necessary nor advisable, and it is almost always better to override only the part you need.

The admin templates are split into blocks for exactly this reason. Extend the original and change one block:

{% extends "admin/change_form.html" %}
{% block object-tools-items %}
  {{ block.super }}
  <li><a href="mylink/">My link</a></li>
{% endblock %}
Adds one link to the top of the edit page and keeps everything else from Django

Where you save the file decides how far the change reaches:

Save it asIt changes
templates/admin/change_form.htmlEvery edit page in the admin
templates/admin/my_app/change_form.htmlEdit pages for one app
templates/admin/my_app/page/change_form.htmlThe edit page for one model (use the lowercase model name)

You can also point a single ModelAdmin at a template with options like change_form_template and change_list_template.

Add your own page inside the admin

If you need a report or a tool that isn't a model, you can add a page to the admin without building a separate site. A ModelAdmin can add its own URLs through get_urls(). Wrap the view in admin_site.admin_view() so Django checks that the person is signed-in staff, and put your URLs before the default ones.

from django.contrib import admin
from django.template.response import TemplateResponse
from django.urls import path


class OrderAdmin(admin.ModelAdmin):
    def get_urls(self):
        urls = super().get_urls()
        my_urls = [
            path("report/", self.admin_site.admin_view(self.report_view)),
        ]
        return my_urls + urls

    def report_view(self, request):
        context = dict(
            self.admin_site.each_context(request),
            title="Order report",
        )
        return TemplateResponse(request, "admin/orders/report.html", context)

Your report.html template should extend admin/base_site.html, so the page keeps the admin's header, navigation, and look.

What Django 6.1 changed for customized admins

Customizations that touch templates or CSS depend on how the admin page is built, and Django 6.1 (released on August 5, 2026) changed some of that. If you have overrides, these are the changes worth checking:

  • Edit forms have a new layout. Fields now sit below their labels instead of next to them. Help text comes after the label, and validation errors come before the input. Checkboxes keep their old layout.
  • The wide class is gone. The new layout made it obsolete.
  • The object-tools block moved. In forms, it is no longer inside the content block.
  • Breadcrumbs changed. They are now list items inside an ordered list instead of div elements, and the current page is marked with aria-current="page".
  • Overriding get_actions() or get_action_choices() without the new action_location parameter is deprecated.

None of these breaks a project that only uses ModelAdmin options. They matter when your CSS targets the old structure or when you copied a whole template.

When a theme is the better choice

Small, targeted changes are what these tools are good at. They get harder when you want the whole admin to feel different: a new navigation, a consistent look across tables and forms, a dark mode, a layout that works on smaller screens. At that point you are overriding many templates and carrying a pile of CSS, and every Django release means checking all of it again.

That is the work a theme takes over. A maintained theme does the restyling once, follows Django's changes, and leaves your models, permissions, and forms where they are. Vanta Admin is built this way: it sits on top of the Django admin you already have instead of asking you to build a separate back office.

A theme won't write your business rules, and you don't need one just to rename the admin or change a color. My rule of thumb is simple. If one or two small overrides solve your problem, keep them. If you are on your fifth template override and still not happy, look at a theme.

A short checklist before you customize

  • Check whether a ModelAdmin option already does what you want.
  • Change the admin site's titles before you touch any templates.
  • Override one template block instead of copying a whole file.
  • Keep your templates and CSS in your own project folders.
  • Add a short comment to each override saying why it exists.
  • Open every overridden page in light and dark mode.
  • After each Django upgrade, check the pages you have overridden.

Back to blog

Expanded article image

Loading image…