Getting Started with the Admin

In this tutorial, you will set up the Django administration interface, register your models for management, and create a customized admin site with unique branding.

Prerequisites

To follow this guide, you need:

• A Django project with django.contrib.auth and django.contrib.contenttypes in your INSTALLED_APPS.
• At least one model defined in your project (e.g., a Book model in a library app).

Step 1: Enable the Admin Application

The Django admin is powered by the AdminConfig class, which handles the automatic discovery of admin configurations across your project.

In your settings.py file, ensure that django.contrib.admin is included in your INSTALLED_APPS:

INSTALLED_APPS = [
    # ... other apps
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # ... your apps
]

When you include "django.contrib.admin", Django uses the AdminConfig class found in django/contrib/admin/apps.py. This class triggers self.module.autodiscover() when the application starts, which searches for an admin.py file in every installed application.

Step 2: Register a Model with the Default Site

To manage a model through the admin interface, you must register it with an AdminSite instance. By default, Django provides a pre-instantiated site at django.contrib.admin.site.

Create a file named admin.py inside your application directory (e.g., library/admin.py) and add the following code:

from django.contrib import admin
from .models import Book

# Register your model with the default admin site
admin.site.register(Book)

The admin.site.register() method (defined in django/contrib/admin/sites.py) adds your model to the internal _registry. If you attempt to register the same model twice, it will raise an AlreadyRegistered error. Note that abstract models cannot be registered and will raise an ImproperlyConfigured error.

Step 3: Create a Custom Admin Site

If you need to change the branding or behavior of the admin interface, you can subclass AdminSite. This allows you to override default attributes like the site header and index title.

In one of your project files (e.g., myproject/admin.py), define your custom site:

from django.contrib.admin import AdminSite
from django.utils.translation import gettext_lazy as _

class MyLibraryAdminSite(AdminSite):
    # Text to put in each page's <div id="site-name">.
    site_header = _("Library Management System")
    
    # Text to put at the end of each page's <title>.
    site_title = _("Library Admin")
    
    # Text to put at the top of the admin index page.
    index_title = _("Welcome to the Library Portal")

# Instantiate your custom site
library_admin_site = MyLibraryAdminSite(name="library_admin")

By overriding these attributes from django/contrib/admin/sites.py, you customize the visual identity of the admin without modifying any templates.

Step 4: Configure Admin URLs

To make your admin interface accessible, you must hook the AdminSite.urls property into your project's URL configuration.

Open your project's urls.py and include the URLs for both the default site and your custom site:

from django.urls import path
from django.contrib import admin
from myproject.admin import library_admin_site

urlpatterns = [
    # The default admin site
    path("admin/", admin.site.urls),
    
    # Your custom admin site
    path("library-admin/", library_admin_site.urls),
]

The urls property returns a tuple containing the URL patterns, the app name (always "admin"), and the instance name. This allows you to host multiple admin sites within the same project.

Step 5: Advanced - Global Customization via AppConfig

If you want your custom AdminSite to be the default site used by the admin.site shortcut and the register decorator, you can create a custom AppConfig.

1. Define a custom configuration in myproject/apps.py:

from django.contrib.admin.apps import SimpleAdminConfig

class MyAdminConfig(SimpleAdminConfig):
    default_site = "myproject.admin.MyLibraryAdminSite"

2. In settings.py, replace "django.contrib.admin" with your custom config:

INSTALLED_APPS = [
    "myproject.apps.MyAdminConfig",  # Replaces django.contrib.admin
    # ...
]

Using SimpleAdminConfig instead of AdminConfig prevents automatic discovery, giving you full control over which models are registered and where. If you still want autodiscovery but with a custom site, your MyAdminConfig should inherit from AdminConfig instead.

Complete Result

You now have a functional administration interface. You can access the default admin at /admin/ and your branded library portal at /library-admin/. Any model registered in library/admin.py using admin.site.register(Book) will appear in the default site, while models registered with library_admin_site.register(Book) will appear in your custom portal.

To further customize the interface, you can now explore creating ModelAdmin classes to control how individual models are displayed and edited.