How to Customize Admin List Display in Django

To customize the admin list display in Django, define a ModelAdmin class for your model and set the list_display attribute to a tuple of field names you want to show as columns. Then register the model with this admin class using admin.site.register().

Syntax

In Django admin, you customize the list display by creating a ModelAdmin class and setting its list_display attribute to a tuple of field names or methods. Then you register your model with this admin class.

• class YourModelAdmin(admin.ModelAdmin): - Defines admin options for your model.
• list_display = ('field1', 'field2', ...) - Specifies which fields show as columns in the list view.
• admin.site.register(YourModel, YourModelAdmin) - Registers the model with the customized admin.

python

from django.contrib import admin
from .models import YourModel

class YourModelAdmin(admin.ModelAdmin):
    list_display = ('field1', 'field2', 'field3')

admin.site.register(YourModel, YourModelAdmin)

Example

This example shows how to customize the Django admin list display for a Book model to show the title, author, and published year as columns.

python

from django.contrib import admin
from .models import Book

class BookAdmin(admin.ModelAdmin):
    list_display = ('title', 'author', 'published_year')

admin.site.register(Book, BookAdmin)

Output

In the Django admin site, the Book list page will show columns: Title | Author | Published Year

Common Pitfalls

Common mistakes when customizing list_display include:

• Using field names that do not exist on the model causes errors.
• For methods in list_display, forgetting to add @admin.display decorator or setting short_description for column name.
• Not registering the model with the custom ModelAdmin class.

Always verify field names and method signatures.

python

from django.contrib import admin
from .models import Book

# Wrong: field 'author_name' does not exist
class BookAdminWrong(admin.ModelAdmin):
    list_display = ('title', 'author_name')  # This will cause an error

# Right: use existing field or method
class BookAdminRight(admin.ModelAdmin):
    list_display = ('title', 'author')

admin.site.register(Book, BookAdminRight)

Quick Reference

Feature	Description	Example
list_display	Fields or methods to show as columns	list_display = ('title', 'author')
Custom method	Add method to ModelAdmin to show computed data	def full_name(self, obj): return f"{obj.first} {obj.last}"
admin.display decorator	Decorate methods to customize column name	@admin.display(description='Full Name')
Register admin	Connect model with admin class	admin.site.register(Book, BookAdmin)

Key Takeaways

Set the list_display attribute in a ModelAdmin class to customize admin list columns.

Only use valid model fields or properly decorated methods in list_display.

Always register your model with the custom ModelAdmin class.

Use @admin.display decorator to customize method columns in list_display.

Test your admin changes to avoid errors from invalid field names.