Most Django developers see apps.py, when starting a new app, then ignore it, and move on.

That works - until your project grows.

Then apps.py becomes one of the most important files in your architecture.

It controls:

• app registration
• startup behavior
• signal loading
• app metadata
• labels and naming
• initialization hooks
• reusable app integration

Used correctly, it keeps projects clean.

Used badly, it causes startup bugs, duplicate execution, circular imports, and performance problems.

This guide explains apps.py in detail.

If you want to know how to use apps.py when organizing your apps, read this article: Organizing Django Apps

What Is apps.py?

Every Django app can define an AppConfig class inside apps.py.

Example:

1
2
3
4
5

from django.apps import AppConfig

class UsersConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "users"

This tells Django:

• the app exists
• its Python path
• metadata about the app
• how to initialize it

Why Django Uses It

When Django starts:

• reads INSTALLED_APPS
• loads each app
• creates AppConfig instances
• builds model registry
• runs startup hooks

Core Fields in AppConfig

name

The full Python path of the app.

1

name = "orders"

Required in each app to initialize properly.

Nested App Structures:

If using enterprise layout:

apps/
    orders/
        apps.py

Then:

1
2

class UsersConfig(AppConfig):
    name = "apps.orders"

We have a full article, explaining Django Enterprise Structure: Organize Enterprise-Scale Projects

The name specified in apps.py must match the Python path.

label

Short internal app label.

Default:

"orders"

Custom:

label = "sales_orders"

Used in:

• migrations
• model refs
• table naming
• admin internals

App Labels Matter for internal representation of the app.

Suppose:

1
2

name = "apps.users"
label = "users"

Then model refs use:

1

ForeignKey("users.Profile")

not:

1

ForeignKey("apps.users.Profile")

Because model refs use the app's label.

verbose_name

Property to define a human readable name.

1

verbose_name = "Order Management"

One application for this is the Admin Panel. If a verbose_name is defined, the admin panel uses the specified value, making the Admin sidebar look cleaner.

default_auto_field

Controls primary key type for every model specified inside this app.

1

default_auto_field = "django.db.models.BigAutoField"

Example Full Config:

1
2
3
4
5
6
7

from django.apps import AppConfig

class OrdersConfig(AppConfig):
    name = "apps.orders"
    label = "orders"
    verbose_name = "Orders"
    default_auto_field = "django.db.models.BigAutoField"

The ready() Method

Runs when Django finishes loading the app registry.

Example:

1
2
3
4
5

class OrdersConfig(AppConfig):
    name = "apps.orders"

    def ready(self):
        import apps.orders.signals

Used for:

• signal registration
• startup checks
• monkey patches (rare)
• app bootstrapping

This is probably the most important feature. The ready() method runs after the app has been fully initilized.

Why ready() Exists

Django models may not be loaded safely at import time.

This fails often:

1

from users.models import User

during startup.

But inside ready(), app registry is initialized.

Important Warning: ready() Can Run Multiple Times

Especially in:

• development autoreload
• tests
• management commands
• gunicorn preload scenarios

So this is misleading:

1
2

def ready(self):
    print("RUNNING")

You may see it twice.

Therefore: ready() Must Be Idempotent

Meaning safe if run multiple times.

Safe:

1
2

def ready(self):
    import apps.orders.signals

Dangerous:

1
2
3

def ready(self):
    send_email(...)
    create_database_rows(...)

Never put side effects in ready().

Most Common Use for ready(): Signals

Django needs to import your signals.py file at startup so that any signal receivers inside it get connected.

This signal only works if Django actually imports apps.users.signals.

A tempting way to do that is inside models.py:

1

import signals

But that is usually not ideal.

models.py should mainly define database models. Importing signals.py from there can create messy import chains, especially because signals.py often imports models.

You can accidentally create something like this:

    models.py imports signals.py
    signals.py imports models.py

That can lead to circular import errors or partially loaded modules.

Instead, Django provides ready() for startup code:

1
2

def ready(self):
    import apps.users.signals

Now the flow is cleanly defined:

• Django loads installed apps
• Django loads models
• Django finishes setting up app registry
• Django calls ready()
• ready() imports signals.py
• signal handlers are registered

What NOT to Put in ready()

• Database Writes
  • User.objects.create(...)
  • Migrations may not be ready.
• External API Calls
  • requests.get(...)
  • Slows startup and may fail deploys.
• Long Tasks
  • rebuild_cache()
  • Use Celery/cron/management command.
• Business Logic
  • ready() is for initialization, not domain workflows.

Valid Use Cases for ready()

• Signal Imports
  • import app.signals
• Registry Setup
  • plugin_registry.register(...)
• Validation Checks
  • assert settings.TIME_ZONE
• Monkey Patching (Rare)
  • Advanced use only.

Reusable Third-Party Apps

For a reusable third-party app, apps.py is especially important because the app cannot assume much about the host project. It may be installed in many different projects with different models, settings, admin setups, and optional integrations.

Good reusable apps use apps.py for:

• signal hookup
• autodiscovery
• config defaults
• admin registration
• system checks

The AppConfig gives the reusable app a clean startup hook and a place to centralize app-level behavior without having to know much about the host project.

default_app_config (Old Django versions)

Older versions used:

1

default_app_config = "users.apps.UsersConfig"

Modern Django no longer needs this in most cases.

Common Mistakes

1. Putting Logic in init.py

If you want behavior on init, use ready not inside the app's init.py

Use ready() to load logic.

2. Querying DB in ready()

Causes migration/startup issues.

3. Importing Models Too Early

Don't import during app import chain.

1

from users.models import User

Import after app init.

4. Using Non-Idempotent Code

Can run multiple times.

5. Wrong name

Wrong naming:

1

name = "users"

when actual path is:

1

apps.users

Example Production apps.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from django.apps import AppConfig



class BillingConfig(AppConfig):
    name = "apps.billing"
    label = "billing"
    verbose_name = "Billing"
    default_auto_field = "django.db.models.BigAutoField"

    def ready(self):
        import apps.billing.signals 

Simple and clean.

apps.py is Django’s startup contract for each app.

Use it for:

• metadata
• registration
• signal imports
• safe initialization

Don't use it for:

• DB writes
• network calls
• business logic
• expensive tasks

If code should happen because Django started, it may belong in apps.py.

If code should happen because business logic occurred, it does not.