How to Get Started with Django Admin

The admin panel is one Django’s most powerful features. It’s the place where developers and administrators can interact with the database in a visual way.

When you’re working on an enterprise scale codebase, I can’t stress how useful having the panel is. In other frameworks, you may need to build the UI for administrators yourself, which can be very time consuming.

I’m going to cover the steps to get started with the admin panel, located at localhost:8000/admin. This is going to involve creating a superuser so you can log in; registering models, and adding some very basic customisation.

I’m going to assume you already have a model set up. If you don’t, this tutorial will get you set up in no time.

Let’s get started!

1. Create a superuser

So you navigate to localhost:8000/admin for the first time and see this screen:

You will need to create a superuser, which you can do from your terminal. You don’t have to stop your server to do this, just open a new terminal window

First make sure your terminal is in the same directory as manage.py. If you’re unsure, type pwd to into your terminal to display your current working direct and ls to display the contents.

Then, in the terminal, type python manage.py createsuperuser

The terminal will prompt you for a username, email and password. The username and password cannot be blank, but they can be short, which is fine if you’re just developing locally. You may get a warning when you put in a short password Bypass password validation and create user anyway? [y/N] but that’s easily by-passed.

After completing the prompts, you can return to localhost:8000/admin and enter the credentials you just created.

2. Register your models

If you haven’t registered any models, your admin panel will look something like this:

To proceed with this tutorial, you will need to create a model and migrate it to the database. There’s a tutorial for that here.

Go to admin.py, this file is located in the same directory as models.py

Enter the following code, substituting Post with the name of your model.

from django.contrib import admin
from . import models

admin.site.register(models.Post)

Save the file and return to /admin, your model should now appear:

4. Customise the list view

By default, the string representation of an object is represented with just the model name and the primary key (ID):

We can change the representation from “Post object (1)” to something that is more meaningful.

Option 1: Define the __str__ model method

• Go to your model in models.py
• Define a new method called __str__. This will have one argument, self.
  • If you’re not yet familiar with object-orientated programming, self refers to an instance of a class (in this case, a row in the database).
  • Methods whose names start and end with a double underscore are called “dunder methods” or “magic methods”. There’s nothing particularly magic about them. Dunder methods i.e. __init__, __str__ are available on all Python classes automatically without inheritance. The double underscore differentiates them from methods defined by the developer or by Django.
• Make the method return a string. Use f-strings to insert attributes of the model.

class Post(models.Model):
    ...
    
    def __str__(self):
        return f"{self.title}, by {self.author.username}"

Refresh /admin (you don’t need to make a migration). Mine now looks like this:

Option 2: Use columns

• This option doesn’t require any changes to your model.
• Go into admin.py and define a class that will contain your customisations for that model in admin.
  • The class must inherit from admin.ModelAdmin
  • The class name should be the name of your model followed by ‘Admin’, e.g. PostAdmin
  • The class must be placed before admin.site.register(...)
• Set an attribute called list_display. Its value should be a list of model attributes that you want to use as columns. I’m using a blog post model, so I have gone for the title, the post status and the author.
• Make sure you state the name of your admin class when registering the model.

from django.contrib import admin
from . import models


class PostAdmin(admin.ModelAdmin):
    list_display = ["title", "status", "author"]

admin.site.register(models.Post, PostAdmin)

My admin now looks like this:

Troubleshooting

You’ve registered the model in admin.py, but it still doesn’t show up

Go to settings.py and make sure that the app (the name of the folder that contains admin.py and models.py) is listed in INSTALLED_APPS

You’ve set list_display in your admin class, but the columns aren’t showing up

Go to the line where you registered the model in admin and add the class name as the second argument.

Incorrect: admin.site.register(models.Post)

Correct: admin.site.register(models.Post, PostAdmin)

You get this error: TypeError: PostAdmin() takes no arguments

Make sure the admin class (PostAdmin in my case) inherits from admin.ModelAdmin. admin is a module imported from django.contrib.

Conclusion

In this tutorial, we have covered:

• Creating a superuser using the python manage.py createsuperuser command.
• Registering a model in admin.py so that our model shows up in localhost:8000/admin
• Customising the list view so we can see the objects in our database in a meaningful way.