Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 77 ยท Getting Started

Projects, Apps and Settings

Understand the difference between a Django project and an app, how INSTALLED_APPS and AppConfig work, and how to manage settings, DEBUG and secrets safely.

Two words cause most of the early confusion in Django: project and app. A project is one website. An app is one feature of that website. Once you understand how they relate, and how the settings file ties them together, the layout of any Django codebase makes sense.

This lesson covers the difference between projects and apps, how Django discovers apps through INSTALLED_APPS and AppConfig, and how to organize settings so the same code runs on your laptop and on a production server without leaking secrets.

Project versus app

A project is the whole site: configuration, URL root, and a list of the apps it uses. An app is a Python package that does one job: a blog, a shop, user profiles, a payment integration. An app can bundle models, views, templates, static files, migrations, management commands and tests.

flowchart TD
    P["Project: mysite<br/>settings.py, urls.py"]
    P --> A1["App: blog"]
    P --> A2["App: shop"]
    P --> A3["App: accounts"]
    P --> B1["Built-in: django.contrib.auth"]
    P --> B2["Built-in: django.contrib.admin"]
    P --> T["Third-party: django-filter"]

A project is a list of apps. Built-in, third-party and your own apps are all treated the same way.

Some rules of thumb:

  • One project, many apps. An app should do one thing that you could describe in a sentence. If the sentence needs "and", consider two apps.
  • An app should be reusable in principle. Even if you never reuse it, thinking that way keeps apps from depending on each other's internals.
  • There is no penalty for more apps. Beginners often put everything into one huge app. Splitting when it starts to hurt is fine, but splitting models later is harder than starting with sensible boundaries.
  • Django's own features are apps too. The admin, authentication, sessions and static-files support are all in django.contrib.

INSTALLED_APPS

INSTALLED_APPS in settings.py is the list of apps Django loads. Putting an app there makes Django:

  • discover its models and include them in migrations;
  • find its templates (in templates/ folders, when the app loader is enabled) and static files;
  • register its management commands and template tags;
  • run its AppConfig.ready() method at startup.

An app that is not listed is invisible to all of that. A model in an unlisted app raises an error, its migrations never run, and its templates are not found. When "my model is not in the database" or "my template cannot be found" puzzles you, check INSTALLED_APPS first.

Entries are either a plain package name ("blog") or the dotted path to the app's configuration class ("blog.apps.BlogConfig"). They are equivalent when the app has a single AppConfig. Order matters in two cases: when two apps provide a template with the same name, the first listed wins, and the same goes for management commands and static files.

AppConfig: describing an app

Each app has an AppConfig class, normally in apps.py. It gives Django the app's Python path, a unique label (which becomes the prefix of the database table names, like blog_post) and a human-friendly name for the admin. It is also the place for startup code in ready(), for example to connect signals.

The next example registers a small blog app in code and inspects Django's app registry. A real app would live in a folder with apps.py; here a stand-in module plays that role.

Python Apps, labels and the app registry

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the output from the top. BlogConfig.ready() ran during django.setup(), before any request. The labels contenttypes, auth and blog are what Django uses internally, and the table name blog_post is the label plus the lowercase model name. The last few lines show ALLOWED_HOSTS rejecting a request whose Host header is not on the list; we come back to that below.

Settings: one place for configuration

settings.py is an ordinary Python module, and every setting is an uppercase name. You read them anywhere through django.conf.settings; never import settings.py directly, because the settings object also provides defaults for everything you did not set and respects overrides during tests.

The most important settings:

Setting Meaning
BASE_DIR Root folder of the project; other paths are built from it.
SECRET_KEY Secret used for signing sessions, tokens and password-reset links.
DEBUG Turns on detailed error pages and developer conveniences.
ALLOWED_HOSTS Hostnames this site may be served from.
INSTALLED_APPS Active apps.
MIDDLEWARE Request/response processing layers.
ROOT_URLCONF Dotted path of the main URL configuration.
TEMPLATES Template engines and where to look for templates.
DATABASES Database connections.
STATIC_URL, STATIC_ROOT Static file URL prefix and collection folder.
TIME_ZONE, USE_TZ Time zone handling (keep USE_TZ = True).

BASE_DIR

The generated file defines it as BASE_DIR = Path(__file__).resolve().parent.parent: the folder that contains manage.py, found by walking up from the settings file. Build every other path from it (BASE_DIR / "db.sqlite3", BASE_DIR / "templates") instead of hard-coding /home/me/project, and your project works wherever it is checked out.

DEBUG

DEBUG = True is wonderful in development: error pages show source code and variables, and static files are served automatically. In production it is dangerous. Debug pages leak settings, paths and secrets, memory use grows because Django keeps SQL history, and attackers gain information. Never run production with DEBUG = True. That is why DEBUG must be driven by the environment, not hard-coded to True.

ALLOWED_HOSTS

When DEBUG is off, Django answers only requests whose Host header matches ALLOWED_HOSTS. This blocks attacks that forge the header (for example to poison password-reset links). A request with another host gets a 400 Bad Request, exactly like the live example above. Typical production value: ["example.com", "www.example.com"]. With DEBUG = True and an empty list, localhost, 127.0.0.1 and [::1] are allowed automatically.

SECRET_KEY

SECRET_KEY signs sessions, cookies and tokens. If it leaks, attackers can forge them. Never commit the production key to a repository, and use a different one per environment. The key startproject generates is only suitable for development.

Settings per environment and environment variables

Your laptop and your server need different settings: different database, DEBUG, hosts and keys. There are two common approaches:

  1. Environment variables. One settings.py reads values from the environment (os.environ). The server sets DJANGO_SECRET_KEY and friends; your laptop uses safe defaults. This is the approach of the "twelve-factor" style and works with Docker, systemd and every hosting platform.
  2. A settings package (settings/base.py, dev.py, prod.py), where each environment imports from base and overrides what differs. You pick one with DJANGO_SETTINGS_MODULE.

Many teams combine them: a shared base, with secrets always from the environment. Whichever you choose, keep two rules: defaults must be safe (DEBUG off unless asked) and secrets never live in version control.

The next example implements the environment-variable approach as a function, so you can run it for two environments side by side, then feeds the production result into settings.configure() and inspects it through django.conf.settings.

Python Settings driven by environment variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Two details worth noticing. With no environment variables, DEBUG is False, so forgetting to configure a server fails safe. And settings.LANGUAGE_CODE returns Django's built-in default (en-us) although we never set it: django.conf.settings merges your values over django.conf.global_settings. In a real project you would use os.environ in place of the dictionaries and a library such as django-environ or python-decouple if you want typed parsing, but plain os.environ is enough.

Do not put real secrets in files you commit, and do not paste them into tutorials, issues or chat. Keep a .env file out of Git (add it to .gitignore) or use your host's secret store. If a secret ever lands in a public repository, assume it is compromised and rotate it.

Checking your configuration

Django can audit your settings. python manage.py check finds mistakes such as a missing app or a bad middleware path, and python manage.py check --deploy warns about production problems: DEBUG on, a weak SECRET_KEY, missing HTTPS settings. Run the second command before every first deployment. The security lesson covers each warning in turn.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the relationship between a Django project and its apps?

    The project is the whole site and its settings. Apps are the pluggable pieces (blog, shop, auth) listed in INSTALLED_APPS.
  2. 2. You created a model in a new app, but its table never appears after migrate. What is the most likely cause?

    Only apps listed in INSTALLED_APPS are scanned for models and migrations.
  3. 3. What does ALLOWED_HOSTS protect against when DEBUG is False?

    Django rejects requests whose Host header is not on the list with a 400 response, which blocks Host-header attacks.
  4. 4. Why should DEBUG come from an environment variable that defaults to False?

    A safe default means that forgetting to configure the server never turns on debug pages that leak secrets.

Summary

  • A project is one site; apps are its features. Built-in, third-party and your own apps are listed in INSTALLED_APPS.
  • Each app has an AppConfig giving its label, name and a ready() hook; the label prefixes table names.
  • Read settings through django.conf.settings, which also supplies defaults.
  • Build paths from BASE_DIR; never hard-code machine-specific paths.
  • Keep DEBUG off by default, set ALLOWED_HOSTS in production, and keep SECRET_KEY out of version control.
  • Drive environment differences with environment variables or a settings package, and audit with check --deploy.

Next lesson: The Request and Response Cycle.