Django contains a registry of installed applications that stores configuration
and provides introspection. It also maintains a list of available models.

This registry is simply called apps and it’s available in

>>> 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

The term application describes a Python package that provides some set of
features. Applications may be reused in various

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

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

Configuring applications¶

To configure an application, subclass AppConfig and put
the dotted path to that subclass in INSTALLED_APPS.

When INSTALLED_APPS simply contains the dotted path to an
application module, Django checks for a default_app_config variable in
that module.

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

If there is no default_app_config, Django uses the base
AppConfig class.

default_app_config allows applications that predate Django 1.7 such as
django.contrib.admin to opt-in to AppConfig features
without requiring users to update their INSTALLED_APPS.

New applications should avoid default_app_config. Instead they should
require the dotted path to the appropriate AppConfig
subclass to be configured explicitly in INSTALLED_APPS.

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"

You can make your application load this AppConfig
subclass by default as follows:

# 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.

Of course, you can also tell your users to put
'rock_n_roll.apps.RockNRollConfig' in their INSTALLED_APPS
setting. You can even provide several different
AppConfig subclasses with different behaviors and allow
your users to choose one via their INSTALLED_APPS setting.

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

You must include the name attribute for Django
to determine which application this configuration applies to. You can define
any attributes documented in the AppConfig API


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

# anthology/

from rock_n_roll.apps import RockNRollConfig

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

# anthology/

    # ...

Again, defining project-specific configuration classes in a submodule called
apps is a convention, not a requirement.

Application configuration¶

class AppConfig[source]

Application configuration objects store metadata for an application. Some
attributes can be configured in AppConfig
subclasses. Others are set by Django and read-only.

Configurable attributes¶

Full Python path to the application, e.g. 'django.contrib.admin'.

This attribute defines which application the configuration applies to. It
must be set in all AppConfig subclasses.

It must be unique across a Django project.


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

This attribute allows relabeling an application when two applications
have conflicting labels. It defaults to the last component of name.
It should be a valid Python identifier.

It must be unique across a Django project.


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

This attribute defaults to label.title().


Filesystem path to the application directory, e.g.

In most cases, Django can automatically detect and set this, but you can
also provide an explicit override as a class attribute on your
AppConfig subclass. In a few situations this is
required; for instance if the app package is a namespace package with
multiple paths.

Read-only attributes¶


Root module for the application, e.g. <module 'django.contrib.admin' from


Module containing the models, e.g. <module 'django.contrib.admin.models'
from 'django/contrib/admin/'>

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



Returns an iterable of Model classes for this

Requires the app registry to be fully populated.

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

Returns the Model with the given
model_name. model_name is case-insensitive.

Raises LookupError if no such model exists in this application.

Requires the app registry to be fully populated unless the
require_ready argument is set to False. require_ready behaves
exactly as in apps.get_model().

New in Django 1.11:

The require_ready keyword argument was added.


Subclasses can override this method to perform initialization tasks such
as registering signals. It is called as soon as the registry is fully

Although you can’t import models at the module-level where
AppConfig classes are defined, you can import them in
ready(), using either an import statement or

If you’re registering model signals, you
can refer to the sender by its string label instead of using the model
class itself.


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')


Although you can access model classes as described above, avoid
interacting with the database in your ready() implementation.
This includes model methods that execute queries
delete(), manager methods etc.), and
also raw SQL queries via django.db.connection. Your
ready() method will run during startup of every management
command. For example, even though the test database configuration is
separate from the production settings, test would still
execute some queries against your production database!


In the usual initialization process, the ready method is only called
once by Django. But in some corner cases, particularly in tests which
are fiddling with installed applications, ready might be called more
than once. In that case, either write idempotent methods, or put a flag
on your AppConfig classes to prevent re-running code which should
be executed exactly one time.

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).

Django applications require a single base filesystem path where Django
(depending on configuration) will search for templates, static assets,
etc. Thus, namespace packages may only be Django applications if one of the
following is true:

  1. The namespace package actually has only a single location (i.e. is not
    spread across more than one directory.)
  2. The AppConfig class used to configure the application
    has a path class attribute, which is the
    absolute directory path Django will use as the single base path for the

If neither of these conditions is met, Django will raise

Application registry¶


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


Boolean attribute that is set to True after the registry is fully
populated and all AppConfig.ready() methods are called.


Returns an iterable of AppConfig instances.


Returns an AppConfig for the application with the
given app_label. Raises LookupError if no such application


Checks whether an application with the given name exists in the registry.
app_name is the full name of the app, e.g. 'django.contrib.admin'.

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

Returns the Model with the given app_label
and model_name. As a shortcut, this method also accepts a single
argument in the form app_label.model_name. model_name is

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

Requires the app registry to be fully populated unless the
require_ready argument is set to False.

Setting require_ready to False allows looking up models
while the app registry is being populated,
specifically during the second phase where it imports models. Then
get_model() has the same effect as importing the model. The main use
case is to configure model classes with settings, such as

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

New in Django 1.11:

The require_ready keyword argument was added.

Initialization process¶

How applications are loaded¶

When Django starts, django.setup() is responsible for populating the
application registry.


Configures Django by:

  • Loading the settings.
  • Setting up logging.
  • If set_prefix is True, setting the URL resolver script prefix to
    FORCE_SCRIPT_NAME if defined, or / otherwise.
  • Initializing the application registry.

This function is called automatically:

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

It must be called explicitly in other cases, for instance in plain Python

The application registry is initialized in three stages. At each stage, Django
processes all applications in the order of INSTALLED_APPS.

  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.

    Once this stage completes, APIs that operate on application configurations
    such as get_app_config() become usable.

  2. Then Django attempts to import the models submodule of each application,
    if there is one.

    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.

    Once this stage completes, APIs that operate on models such as
    get_model() become usable.

  3. Finally Django runs the ready() method of each application


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

  • AppRegistryNotReady: This happens when
    importing an application configuration or a models module triggers code that
    depends on the app registry.

    For example, gettext() uses the app
    registry to look up translation catalogs in applications. To translate at
    import time, you need gettext_lazy()
    instead. (Using gettext() would be a bug,
    because the translation would happen at import time, rather than at each
    request depending on the active language.)

    Executing database queries with the ORM at import time in models modules
    will also trigger this exception. The ORM cannot function properly until all
    models are available.

    This exception also happens if you forget to call django.setup() in
    a standalone Python script.

  • ImportError: cannot import name ... This happens if the import sequence
    ends up in a loop.

    To eliminate such problems, you should minimize dependencies between your
    models modules and do as little work as possible at import time. To avoid
    executing code at import time, you can move it into a function and cache its
    results. The code will be executed when you first need its results. This
    concept is known as “lazy evaluation”.

  • django.contrib.admin automatically performs autodiscovery of admin
    modules in installed applications. To prevent it, change your
    INSTALLED_APPS to contain
    'django.contrib.admin.apps.SimpleAdminConfig' instead of