Apps, settings, and project layout

Understanding Apps, settings, and project layout

The directory that startapp creates is inert Python until its dotted path appears in INSTALLED_APPS. At startup Django imports each entry, builds one AppConfig object per app, and stores it in a registry keyed by the app's label. That label defaults to the last component of the package name, and it is the identity used everywhere afterwards: Model._meta.app_label, the default table prefix, the argument to makemigrations, and the key for apps.get_app_config(). If two installed packages end in the same word, their labels collide and Django refuses to start until you set label explicitly on one AppConfig.

Settings are just a Python module whose import path lives in the DJANGO_SETTINGS_MODULE environment variable. Django imports that module exactly once, copies its UPPERCASE module-level names into the lazy django.conf.settings object, and fills every name you did not define from django.conf.global_settings. That is why application code must always do `from django.conf import settings` rather than importing the project module: the lazy object is what environment-specific settings modules, --settings, and override_settings in tests actually swap out. In a script with no manage.py, settings.configure() followed by django.setup() plays the same role.

Because settings are only a module path, layout is a free choice. A common one is to turn settings.py into a settings/ package containing base.py, dev.py, and prod.py, where each environment module starts with `from .base import *` and overrides a handful of names; DJANGO_SETTINGS_MODULE then picks one. The same freedom applies to apps: nesting them under an apps/ package is fine, but then the app's name becomes apps.billing while its label stays billing, and BASE_DIR in settings must still point at the directory you build paths from.

import django
from django.conf import settings

settings.configure(
    INSTALLED_APPS=[
        "django.contrib.contenttypes",
        "django.contrib.auth",
        "django.contrib.sessions",
    ],
)
django.setup()

from django.apps import apps

for config in apps.get_app_configs():
    print(f"{config.label:<14}{config.name:<30}{config.verbose_name}")

print()
print("auth models:", [m.__name__ for m in apps.get_app_config("auth").get_models()])
print("User label:", apps.get_model("auth.User")._meta.label)
print("sessions module:", apps.get_app_config("sessions").models_module.__name__)

Worked examples

from django.conf import settings
from django.core.exceptions import ImproperlyConfigured

print("configured?", settings.configured)

try:
    settings.DEBUG
except ImproperlyConfigured:
    print("reading DEBUG too early raised ImproperlyConfigured")

try:
    settings.configure(debug=True)
except TypeError:
    print("lowercase names are rejected by configure()")

settings.configure(DEBUG=True, PAGE_SIZE=25)
print("configured?", settings.configured)
print("DEBUG:", settings.DEBUG)
print("PAGE_SIZE:", settings.PAGE_SIZE)
print("INSTALLED_APPS default:", settings.INSTALLED_APPS)

import os, sys, tempfile
import django
from django.conf import settings

root = tempfile.mkdtemp()
pkg = os.path.join(root, "store")
os.makedirs(pkg)
open(os.path.join(pkg, "__init__.py"), "w").close()
with open(os.path.join(pkg, "apps.py"), "w") as f:
    f.write(
        "from django.apps import AppConfig\n"
        "class StoreConfig(AppConfig):\n"
        "    name = 'store'\n"
        "    label = 'catalog'\n"
        "    verbose_name = 'Product catalogue'\n"
        "    default_auto_field = 'django.db.models.SmallAutoField'\n"
    )
with open(os.path.join(pkg, "models.py"), "w") as f:
    f.write(
        "from django.db import models\n"
        "class Product(models.Model):\n"
        "    name = models.CharField(max_length=50)\n"
    )
sys.path.insert(0, root)

settings.configure(INSTALLED_APPS=["store.apps.StoreConfig"])
django.setup()

from django.apps import apps

cfg = apps.get_app_config("catalog")
print("label:", cfg.label)
print("name:", cfg.name)
print("verbose_name:", cfg.verbose_name)

Product = apps.get_model("catalog.Product")
print("model label:", Product._meta.label)
print("pk field:", Product._meta.pk.__class__.__name__)
print("table:", Product._meta.db_table)

Important notes

Common mistakes

Try it yourself