

This registry is simply called apps and it's available in django.apps:

>>> from django.apps import apps
>>> apps.get_app_config('admin').verbose_name

Projects and applications

The term project describes a Django web application. The project Python package is defined primarily by a settings module, but it usually contains other things. For example, when you run django-admin startproject mysite you'll get a mysite project directory that contains a mysite Python package with,, and The project package is often extended to include things like fixtures, CSS, and templates which aren't tied to a particular application.

A project's root directory (the one that contains is usually the container for all of a project's applications which aren't installed separately.


Applications include some combination of models, views, templates, template tags, static files, URLs, middleware, etc. They're generally wired into projects with the INSTALLED_APPS setting and optionally with other mechanisms such as URLconfs, the MIDDLEWARE setting, or template inheritance.

It is important to understand that a Django application is just a set of code that interacts with various parts of the framework. There's no such thing as an Application object. However, there's a few places where Django needs to interact with installed applications, mainly for configuration and also for introspection. That's why the application registry maintains metadata in an AppConfig instance for each installed application.

There's no restriction that a project package can't also be considered an application and have models, etc. (which would require adding it to INSTALLED_APPS).

Configuring applications



If it's defined, it's the dotted path to the AppConfig subclass for that application.




For application authors

If you're creating a pluggable app called "Rock ’n’ roll", here's how you would provide a proper name for the admin:

# rock_n_roll/

from django.apps import AppConfig

class RockNRollConfig(AppConfig):
    name = 'rock_n_roll'
    verbose_name = "Rock ’n’ roll"


# rock_n_roll/

default_app_config = 'rock_n_roll.apps.RockNRollConfig'

That will cause RockNRollConfig to be used when INSTALLED_APPS just contains 'rock_n_roll'. This allows you to make use of AppConfig features without requiring your users to update their INSTALLED_APPS setting. Besides this use case, it's best to avoid using default_app_config and instead specify the app config class in INSTALLED_APPS as described next.


The recommended convention is to put the configuration class in a submodule of the application called apps. However, this isn't enforced by Django.



If your code imports the application registry in an application's, the name apps will clash with the apps submodule. The best practice is to move that code to a submodule and import it. A workaround is to import the registry under a different name:

from django.apps import apps as django_apps

For application users

If you're using "Rock ’n’ roll" in a project called anthology, but you want it to show up as "Jazz Manouche" instead, you can provide your own configuration:

# anthology/

from rock_n_roll.apps import RockNRollConfig

class JazzManoucheConfig(RockNRollConfig):
    verbose_name = "Jazz Manouche"

# anthology/

    # ...


Application configuration

class AppConfig[source]


Configurable attributes



It must be unique across a Django project.


Short name for the application, e.g. 'admin'


It must be unique across a Django project.


Human-readable name for the application, e.g. "Administration".

This attribute defaults to label.title().




Read-only attributes





It may be None if the application doesn't contain a models module. Note that the database related signals such as pre_migrate and post_migrate are only emitted for applications that have a models module.



Returns an iterable of Model classes for this application.

Requires the app registry to be fully populated.

AppConfig.get_model(model_name, require_ready=True)[source]


Raises LookupError if no such model exists in this application.


New in Django 1.11:

The require_ready keyword argument was added.






from django.db.models.signals import pre_save

def ready(self):
    # importing model classes
    from .models import MyModel  # or...
    MyModel = self.get_model('MyModel')

    # registering signals with the model's string label
    pre_save.connect(receiver, sender='app_label.MyModel')





Namespace packages as apps

Python packages without an file are known as "namespace packages" and may be spread across multiple directories at different locations on sys.path (see PEP 420).




Application registry


The application registry provides the following public API. Methods that aren't listed below are considered private and may change without notice.




Returns an iterable of AppConfig instances.





apps.get_model(app_label, model_name, require_ready=True)


Raises LookupError if no such application or model exists. Raises ValueError when called with a single argument that doesn't contain exactly one dot.



When require_ready is False, get_model() returns a model class that may not be fully functional (reverse accessors may be missing, for example) until the app registry is fully populated. For this reason, it's best to leave require_ready to the default value of True whenever possible.

New in Django 1.11:

The require_ready keyword argument was added.

Initialization process

How applications are loaded



Configures Django by:

  • Loading the settings.
  • Setting up logging.
  • Initializing the application registry.

This function is called automatically:

  • When running an HTTP server via Django's WSGI support.
  • When invoking a management command.



  1. First Django imports each item in INSTALLED_APPS.

    If it's an application configuration class, Django imports the root package of the application, defined by its name attribute. If it's a Python package, Django creates a default application configuration.

    At this stage, your code shouldn't import any models!

    In other words, your applications' root packages and the modules that define your application configuration classes shouldn't import any models, even indirectly.

    Strictly speaking, Django allows importing models once their application configuration is loaded. However, in order to avoid needless constraints on the order of INSTALLED_APPS, it's strongly recommended not import any models at this stage.



    You must define or import all models in your application's or models/ Otherwise, the application registry may not be fully populated at this point, which could cause the ORM to malfunction.




Here are some common problems that you may encounter during initialization:






