Step-by-Step Guide to Django Custom Management Commands

Django is one of the most popular web frameworks because it helps developers build powerful applications quickly with clean, maintainable code. A big part of this comes from the tools Django provides out of the box — and one of the most important is the management command system.

If you’ve worked with Django, you’ve probably typed commands like:

python manage.py runserver
python manage.py makemigrations
python manage.py migrate

These commands handle everything from running your development server to applying database migrations. But Django doesn’t stop at built-in features — it also gives you the flexibility to create your own commands.

Why is this useful? Think of all the tasks you repeat in your project: cleaning up old data, sending reminders, generating reports, or importing data from a file. Instead of doing them manually, you can write a custom management command and run it with a single line. Even better, you can schedule it to run automatically with tools like cron or Celery.

In this guide, we’ll build a simple custom command step by step so you can see how easy it is to add your own scripts to Django projects like Horilla HRMS.

Step 1: Create the Command Folder

Inside any Django app (let’s say an app named employees), create this structure:

employees/ #OR INSIDE YOUR CUSTOM APP
│
│── management/
│ └── commands/
│ ├── init.py
│ └── hello.py
│
│── models.py

Important: Both management and commands folders must have an __init__.py file (even if it’s empty). This tells Python to treat them as packages.

Step 2: Write Your First Command

Open hello.py and add:

from django.core.management.base import BaseCommand

class Command(BaseCommand):
    help = "A simple command that says hello"

    def handle(self, *args, **options):
        self.stdout.write("Hello from your custom command in Horilla!")

Step 3: Run the Command

In your terminal, run:

python manage.py hello

Output:

Hello from your custom command in Horilla!

Step 4: Add Arguments to Your Command

Commands can take arguments, just like normal scripts.

Update hello.py:

from django.core.management.base import BaseCommand

class Command(BaseCommand):
    help = "Greets a person by name"

    def add_arguments(self, parser):
        parser.add_argument("name", type=str, help="The name of the person")

    def handle(self, *args, **options):
        name = options["name"]
        self.stdout.write(f"Hello, {name}! Welcome to Horilla.")

Now run:

python manage.py hello Horilla

Output:

Hello, Horilla! Welcome to Horilla.

Step 5: Using Optional Arguments

You can also add optional arguments with flags.

from django.core.management.base import BaseCommand
class Command(BaseCommand):
help = "Says hello with an optional uppercase flag"
def add_arguments(self, parser):
parser.add_argument("name", type=str, help="The name of the person")
parser.add_argument(
"--uppercase",
action="store_true",
help="Convert the message to uppercase",
)
def handle(self, *args, **options):
message = f"Hello, {options['name']}! Welcome to Horilla."
if options["uppercase"]:
message = message.upper()
self.stdout.write(message)

Run it:

python manage.py hello Horilla

Output:

Hello, Horilla! Welcome to Horilla.

Run it:

python manage.py hello Horilla –uppercase

Output:

HELLO, HORILLA! WELCOME TO HORILLA.

When Should You Use Custom Commands?

Custom commands are best for tasks you would otherwise repeat manually, such as:

• Importing data from a file
• Sending scheduled emails
• Cleaning up old users or logs
• Exporting reports
• Automating one-time admin tasks

Conclusion

Custom management commands are one of Django’s most underrated features. They allow you to extend your project beyond the usual web requests and give you a flexible way to automate repetitive tasks.

Instead of running the same queries in the shell or writing temporary scripts, you can store your logic in a reusable, testable command that integrates directly with manage.py. This keeps your project cleaner, saves you time, and gives your team tools they can run anytime.

To recap:

• Create a management/commands/ folder inside an app.
• Add a Python file with a Command class.
• Define your logic inside the handle method.
• Run it with python manage.py your_command.

This way, you can save time and automate boring tasks in your Django apps (like Horilla 🚀).