Project Structure

A tour of settings.py

settings.py is an ordinary Python module. These are the settings you will touch most often:

# mysite/settings.py (excerpt)
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = "dev-only-placeholder"
DEBUG = True
ALLOWED_HOSTS = []

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

LANGUAGE_CODE = "en-us"
TIME_ZONE = "UTC"
USE_TZ = True

STATIC_URL = "static/"
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

BASE_DIR is the folder that contains manage.py. With USE_TZ = True, datetimes are stored in UTC and converted to TIME_ZONE for display. DEFAULT_AUTO_FIELD sets the type of the auto-incrementing primary key added to models that do not declare one.

Separating settings per environment

Never hard-code SECRET_KEY or database passwords. The simplest fix is to read them from environment variables.

# mysite/settings.py
import os

SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "dev-only-placeholder")
DEBUG = os.environ.get("DJANGO_DEBUG", "") == "1"
ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "localhost,127.0.0.1").split(",")

As settings grow, many teams turn settings.py into a settings/ package with base.py, dev.py and prod.py, and pick one at runtime through the DJANGO_SETTINGS_MODULE environment variable. Packages such as django-environ can also load values from a .env file.

# Run a management command with the production settings
DJANGO_SETTINGS_MODULE=mysite.settings.prod python manage.py check --deploy

Commands you run through manage.py

You can add your own commands too: create a management/commands/ folder in an app and put a class that subclasses BaseCommand in it. It then runs through manage.py like any built-in command.

Summary

• The project folder holds manage.py and the settings package; each app holds its models, views, admin and migrations.
• Nest templates and static files in a folder named after the app to avoid clashes.
• Pass secrets through environment variables and split settings per environment when needed.
• Automate routine work with manage.py commands, including custom ones.