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.
- If you’re not yet familiar with object-orientated programming,
- 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(...)
- The class must inherit from
- 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 inlocalhost:8000/admin
- Customising the list view so we can see the objects in our database in a meaningful way.