Skip to content
Kuza Ndoto Academy

The Admin Site

IntermediateChapter 4 · Page 15 of 234 min readUpdated 15 Nov 2026

Django comes with a complete admin site: a secure, ready-made dashboard where trusted staff can add, edit, search and delete your data. With a few lines of code, your Campus Events organisers get a working back office without you building a single form.

Step 1: Create a superuser

The admin needs a user account with full permissions. Make sure you've run migrate, then:

python manage.py createsuperuser
Username (leave blank to use 'amina'): amina Email address: amina@example.com Password: Password (again): Superuser created successfully.

The suggested username comes from your computer's user name, so yours will differ. The password isn't shown as you type; that's normal. If your password is short or too common, Django warns you and asks whether to bypass validation. Choose a strong one instead.

Start the server and open http://127.0.0.1:8000/admin/. Log in, and you'll see Groups and Users, from the built-in auth app. Your Event model isn't there yet.

Step 2: Register your model

events/admin.py

from django.contrib import admin

from .models import Event

admin.site.register(Event)

Refresh the admin and an Events section appears. You can now add, view, edit and delete events. The admin builds the forms from your model fields, with date pickers for starts_at, checkboxes for is_free and validation for max_length. Each event is listed by its __str__, which is why defining that method matters.

Step 3: Customise the list page

A plain list of titles gets hard to use once you have hundreds of events. A ModelAdmin class controls how a model appears. Replace the simple registration with this:

events/admin.py

from django.contrib import admin

from .models import Event


@admin.register(Event)
class EventAdmin(admin.ModelAdmin):
    list_display = ["title", "venue", "starts_at", "capacity", "is_free"]
    list_filter = ["is_free", "venue"]
    search_fields = ["title", "description", "venue"]
    date_hierarchy = "starts_at"
    ordering = ["starts_at"]
    list_per_page = 25
OptionEffect
list_displayColumns shown in the list. Click a column heading to sort.
list_filterA sidebar of filters, e.g. "Is free: Yes / No".
search_fieldsAdds a search box that looks through these fields.
date_hierarchyYear, month and day links across the top for drilling into dates.
orderingDefault sort order in the admin.
list_per_pageHow many rows appear on each page.

The @admin.register(Event) decorator does the same as admin.site.register(Event, EventAdmin).

Customising the edit form

You can also control the add/edit page:

@admin.register(Event)
class EventAdmin(admin.ModelAdmin):
    list_display = ["title", "venue", "starts_at", "capacity", "is_free"]
    readonly_fields = ["created_at"]
    fieldsets = [
        (None, {"fields": ["title", "description"]}),
        ("When and where", {"fields": ["venue", "starts_at"]}),
        ("Tickets", {"fields": ["capacity", "is_free", "created_at"]}),
    ]
  • fieldsets groups fields under headings.
  • readonly_fields shows values that can't be edited, such as the automatic created_at.
  • fields (a simple list) chooses which fields appear and in what order, if you don't need headings.

Custom columns and actions

A column can come from a method. Actions let staff change many rows at once from the list page:

events/admin.py

@admin.register(Event)
class EventAdmin(admin.ModelAdmin):
    list_display = ["title", "venue", "starts_at", "is_free", "size"]
    actions = ["make_free"]

    @admin.display(description="Size")
    def size(self, obj):
        return "Large" if obj.capacity >= 200 else "Small"

    @admin.action(description="Mark selected events as free")
    def make_free(self, request, queryset):
        updated = queryset.update(is_free=True)
        self.message_user(request, f"{updated} event(s) marked as free.")

Tick some events, choose "Mark selected events as free" from the Action menu and click Go. The admin also includes a built-in "Delete selected events" action, which asks for confirmation first.

Branding the admin

events/admin.py

admin.site.site_header = "Campus Events Admin"
admin.site.site_title = "Campus Events"
admin.site.index_title = "Manage events and users"

Who should use the admin?

The admin is a tool for trusted staff, such as the student council's events team, not for the public. Only users with is_staff set can log in, and they only see the models their permissions allow. Your public pages, like the event list and sign-up forms, should be built with your own views and templates.

Warning

On a live site, the admin is a target for password-guessing attacks. Use strong passwords, keep superuser accounts to a minimum and consider moving it from admin/ to a less obvious path in campus/urls.py, e.g. path("staff-portal-7k/", admin.site.urls).

Common mistake

Registering the same model twice, e.g. with both admin.site.register(Event) and @admin.register(Event). Django raises AlreadyRegistered. Keep one registration per model.

Key points

  • Create an admin account with python manage.py createsuperuser and log in at /admin/.
  • Register models in admin.py to manage them in the admin.
  • A ModelAdmin class adds columns, filters, search, fieldsets and bulk actions.
  • The admin is for trusted staff; build public pages with your own views.
Up next · Models & DatabasesModel RelationshipsOne-to-many and many-to-many.
→

Tip: use the ← and → keys to move between pages.