How to Add Custom Action in Django Admin: Simple Guide

To add a custom action in Django admin, define a function that performs the action and register it in the actions list of your ModelAdmin class. This function receives the admin request, queryset of selected items, and can modify data or display messages.

Syntax

Define a function for the action with parameters modeladmin, request, and queryset. Then add this function to the actions list inside your ModelAdmin subclass.

The function can modify the selected objects or perform any task, and optionally use modeladmin.message_user() to show feedback.

python

def custom_action(modeladmin, request, queryset):
    # Your action code here
    queryset.update(field=value)  # example
    modeladmin.message_user(request, "Action performed successfully.")

class YourModelAdmin(admin.ModelAdmin):
    actions = [custom_action]

Example

This example shows how to add a custom action that marks selected items as published in the Django admin.

python

from django.contrib import admin
from .models import Article

@admin.action(description='Mark selected articles as published')
def make_published(modeladmin, request, queryset):
    updated = queryset.update(status='published')
    modeladmin.message_user(request, f"{updated} articles marked as published.")

class ArticleAdmin(admin.ModelAdmin):
    list_display = ('title', 'status')
    actions = [make_published]

admin.site.register(Article, ArticleAdmin)

Output

In Django admin, the action 'Mark selected articles as published' appears in the actions dropdown. Selecting articles and applying this action updates their status and shows a success message.

Common Pitfalls

• Forgetting to add the action function to the actions list means the action won't appear.
• Not using @admin.action(description='...') decorator or setting short_description can make the action label unclear.
• Modifying the queryset without saving or using queryset methods properly can cause no changes.
• Not calling modeladmin.message_user() leaves users without feedback.

python

def wrong_action(modeladmin, request, queryset):
    for obj in queryset:
        obj.status = 'published'
        obj.save()  # Added save() to persist changes

class WrongAdmin(admin.ModelAdmin):
    actions = [wrong_action]

# Correct way:
@admin.action(description='Mark selected as published')
def right_action(modeladmin, request, queryset):
    queryset.update(status='published')
    modeladmin.message_user(request, "Updated successfully.")

Quick Reference

Step	Description
Define action function	Function with parameters (modeladmin, request, queryset) that performs the task
Add to actions list	Include the function name in the ModelAdmin's actions attribute
Use @admin.action decorator	Set a user-friendly description for the action
Call message_user	Show feedback message after action completes
Register ModelAdmin	Register your model with the custom ModelAdmin class

Key Takeaways

Define a function with (modeladmin, request, queryset) to create a custom admin action.

Add the function to the ModelAdmin's actions list to make it available in admin.

Use @admin.action decorator to set a clear action name shown in the admin UI.

Always call modeladmin.message_user() to give feedback after the action runs.

Use queryset methods like update() for efficient batch changes.