Manage.Py Explained

1. Introduction

manage.py is a command line tool that sits at the root of every Django project. You use it to run the development server, create database tables, create apps, open a Python shell, and much more. You will use it every single day while working with Django.

In the Getting Started section we used a few basic commands. This page goes deeper — covering how manage.py works internally, all the commands you will use regularly, and how to create your own custom commands.

• You should already have myproject set up with Django 5.2 installed.
• Your .venv must be active and your terminal inside the myproject folder.

2. How manage.py works

When you run any manage.py command, Django does two things before executing it:

1. It reads the DJANGO_SETTINGS_MODULE environment variable to find your settings file.
2. It sets up the Django environment — loading apps, connecting to the database, and applying configuration.

If you open manage.py you will see this at the top:

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')

This line tells Django to use mysite/settings.py by default. If you ever use multiple settings files (for example a separate production settings file), you can override this by setting DJANGO_SETTINGS_MODULE in your terminal before running a command.

3. The most used commands

Here are the commands you will reach for most often, grouped by what they do.

Running the server

# Start the development server on default port 8000
python manage.py runserver

# Start on a different port
python manage.py runserver 8080

Database and migrations

# Create migration files based on model changes
python manage.py makemigrations

# Apply migrations to the database
python manage.py migrate

# Show all migrations and their status
python manage.py showmigrations

# Print the SQL for a migration without running it
python manage.py sqlmigrate appname 0001

Creating projects and apps

# Create a new Django project (used once at the start)
django-admin startproject mysite .

# Create a new app inside the project
python manage.py startapp appname

Users and admin

# Create a superuser for the Django admin panel
python manage.py createsuperuser

# Change a user's password
python manage.py changepassword username

Shell and debugging

# Open a Python shell with Django fully loaded
python manage.py shell

# Run the system check for common problems
python manage.py check

# Clear expired sessions from the database
python manage.py clearsessions

Static files

# Collect all static files into STATIC_ROOT (used in production)
python manage.py collectstatic

Testing

# Run all tests in the project
python manage.py test

# Run tests for a specific app
python manage.py test pages

4. See all available commands

To see every command available in your project, run:

python manage.py help

The output is grouped by category — [django] for built-in commands and your app name for any custom commands you add. To get details on a specific command:

python manage.py help migrate

5. The shell command in detail

The shell command is one of the most useful tools in Django. It opens an interactive Python session with your entire project loaded — models, settings, and all installed apps.

python manage.py shell

Inside the shell you can query the database, test model methods, and experiment with code without writing a view:

>>> from pages.models import Page
>>> Page.objects.all()
>>> Page.objects.filter(title="Hello")
>>> exit()

pip install ipython

6. Custom management commands

You can add your own commands to manage.py. This is useful for tasks like importing data, sending scheduled emails, or cleaning up old records.

To create a custom command inside the pages app, create this folder structure:

pages/
└── management/
    ├── __init__.py
    └── commands/
        ├── __init__.py
        └── hello.py

Inside hello.py, add this:

# pages/management/commands/hello.py

from django.core.management.base import BaseCommand


class Command(BaseCommand):
    help = 'Prints a hello message to the terminal'

    def handle(self, *args, **kwargs):
        self.stdout.write('Hello from manage.py!')

Now run it:

python manage.py hello
# Output: Hello from manage.py!

Custom commands follow the same pattern as built-in ones. You can add arguments, options, and output styling. We cover this in full in the Management Commands section.

7. Next steps

You now have a solid understanding of manage.py and the commands you will use throughout this series. The next step is a full tour of the Django settings file — every key setting explained and what it controls.