Settings Module Overview

1. Introduction

The settings file is the control center of your Django project. Every major behavior — database connection, installed apps, static files, templates, security — is configured here. Understanding what each setting does saves you a lot of time when things do not work as expected.

In this guide we will walk through the most important settings in mysite/settings.py, explain what each one controls, and cover how Django locates and loads the settings file at startup. We will also cover BASE_DIR and how Django handles file paths.

• Your myproject project must already be set up. If not, see Create First Project.
• Your .venv must be active and Django 5.2 installed.

2. How Django loads settings

When Django starts, it looks for an environment variable called DJANGO_SETTINGS_MODULE to find your settings file. manage.py sets this automatically:

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')

This tells Django to import mysite/settings.py as a Python module. You can override this at any time by setting a different value in your terminal before running a command — which is how multiple settings files work. We cover that in the next tutorial.

3. BASE_DIR and path handling

At the top of mysite/settings.py you will see:

from pathlib import Path

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

BASE_DIR is the absolute path to the root of your project — the myproject folder. Django uses it to build reliable paths to other folders like templates, static files, and media.

Here is what each part does:

• __file__ — the full path to settings.py itself.
• .resolve() — converts it to an absolute path, resolving any symlinks.
• .parent — goes up one level to mysite/.
• .parent.parent — goes up one more level to myproject/.

You use BASE_DIR to build paths to other folders in your project:

TEMPLATES = [
    {
        'DIRS': [BASE_DIR / 'templates'],
    }
]

STATIC_ROOT = BASE_DIR / 'staticfiles'
MEDIA_ROOT = BASE_DIR / 'media'

4. SECRET_KEY and DEBUG

SECRET_KEY

SECRET_KEY = 'django-insecure-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Django uses SECRET_KEY to sign cookies, sessions, CSRF tokens, and other security-sensitive data. It must be a long, random, and unique string.

• Never share it or commit it to a public repository.
• In production, load it from an environment variable — not hardcoded in the file.
• If it is ever exposed, generate a new one and redeploy immediately.

DEBUG

DEBUG = True

When DEBUG = True, Django shows detailed error pages with full tracebacks in the browser. This is useful during development but dangerous in production — it exposes internal code, file paths, and settings to anyone who triggers an error. Always set DEBUG = False before deploying.

5. ALLOWED_HOSTS

ALLOWED_HOSTS = []

This is a list of hostnames or IP addresses that Django will accept requests from. It protects against HTTP Host header attacks.

• During development with DEBUG = True, Django allows localhost and 127.0.0.1 automatically — so an empty list is fine.
• In production you must list your actual domain: ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com'].
• If you access the dev server from another device on your network, add your local IP address here too.

6. INSTALLED_APPS

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'pages',
]

This list tells Django which apps are active in the project. Django's own built-in apps are listed first, followed by any apps you create or install. Every app must be listed here for its models, migrations, and template directories to be recognized. We cover this in detail in the INSTALLED_APPS Explained tutorial.

7. DATABASES

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

Django uses SQLite by default. It stores the entire database in a single file called db.sqlite3 at the root of myproject. SQLite requires no setup and is perfectly fine for development.

For production you will switch to PostgreSQL or MySQL. The ENGINE value changes and you add connection details like HOST, PORT, USER, and PASSWORD. We cover database configuration in the Models and Database section.

8. TEMPLATES

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

• DIRS — a list of folders where Django looks for project-wide templates. We add BASE_DIR / 'templates' so Django can find a top-level templates folder.
• APP_DIRS: True — tells Django to also look for templates inside each app's templates/ subfolder.
• context_processors — functions that add variables to every template automatically, like the current user and request object.

9. Static and media settings

STATIC_URL = 'static/'

MEDIA_URL = 'media/'
MEDIA_ROOT = BASE_DIR / 'media'

• STATIC_URL — the URL prefix for static files like CSS, JavaScript, and images.
• MEDIA_URL — the URL prefix for user-uploaded files.
• MEDIA_ROOT — the folder on disk where uploaded files are saved.

10. TIME_ZONE and LANGUAGE_CODE

LANGUAGE_CODE = 'en-us'

TIME_ZONE = 'UTC'

USE_I18N = True

USE_TZ = True

• LANGUAGE_CODE — sets the default language for the project.
• TIME_ZONE — set this to your local timezone, for example 'America/New_York' or 'Europe/London'. Django uses this for displaying dates and times correctly.
• USE_TZ = True — tells Django to store all datetimes in UTC internally and convert to the local timezone for display. Keep this as True.
• USE_I18N = True — enables Django's internationalization system for translations.

11. Next steps

You now understand what the core settings do and how Django loads them. The next step is to split your settings into separate files for development and production — a standard practice for any real Django project.