~3 min read • Updated Mar 15, 2026
Introduction
A Django settings file contains all configuration for your Django project. It is simply a Python module that defines variables at the module level. These variables control everything from database connections to installed apps, middleware, email settings, security options, and more.
Because it is a Python module, a settings file:
- must not contain syntax errors
- can compute values dynamically
- can import values from other modules
Basic Structure of a Settings File
A typical settings file contains entries like:
ALLOWED_HOSTS = ["www.example.com"]
DEBUG = False
DEFAULT_FROM_EMAIL = "[email protected]"
If DEBUG = False, you must set ALLOWED_HOSTS properly.
Designating the Settings Module
Using DJANGO_SETTINGS_MODULE
Django needs to know which settings file to use. This is done via the DJANGO_SETTINGS_MODULE environment variable.
Its value must be a Python path, such as:
mysite.settings
The module must be on sys.path.
Using django-admin
You can set the environment variable:
export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
Or pass the settings file explicitly:
django-admin runserver --settings=mysite.settings
On a WSGI Server
Set the environment variable in your WSGI file:
import os
os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"
Default Settings
Django provides default values for all settings in django/conf/global_settings.py.
Your settings file overrides only what you define.
To see what you’ve changed:
python manage.py diffsettings
Using Settings in Your Code
Import settings like this:
from django.conf import settings
if settings.DEBUG:
...
Important notes:
django.conf.settingsis an object, not a module- You cannot import individual settings directly
- Never import from your settings file or global_settings
Do Not Modify Settings at Runtime
Never do this:
settings.DEBUG = True
Settings should only be defined in a settings file.
Security Considerations
Settings files often contain sensitive data such as:
- database passwords
- API keys
- secret keys
Ensure the file is readable only by trusted users, especially on shared hosting.
Creating Your Own Settings
You can define custom settings for your apps. Follow these rules:
- Setting names must be uppercase
- Don’t duplicate existing Django settings
- Use lists for sequences (convention)
Using Django Without DJANGO_SETTINGS_MODULE
Sometimes you want to use Django components without setting an environment variable. In such cases, configure Django manually:
from django.conf import settings
settings.configure(DEBUG=True)
You can pass any number of keyword arguments. If a setting is not provided, Django uses the default.
Custom Default Settings
You can override Django’s default settings by passing a module or class:
from django.conf import settings
from myapp import myapp_defaults
settings.configure(default_settings=myapp_defaults, DEBUG=True)
This replaces Django’s defaults entirely, so you must define all required settings.
configure() vs DJANGO_SETTINGS_MODULE
You must use exactly one of:
- DJANGO_SETTINGS_MODULE
- settings.configure()
If neither is used, Django raises ImportError.
If both are used, Django raises RuntimeError.
Check whether settings are configured:
if not settings.configured:
settings.configure(...)
Calling django.setup()
If you are using Django in a standalone script (outside django-admin or a web server), you must call:
import django
django.setup()
This loads settings and initializes Django’s application registry.
Only call django.setup() once.
Conclusion
Django’s settings system is flexible, powerful, and essential for configuring your project. By understanding how settings are loaded, how to manage environment variables, how to configure Django manually, and how to secure sensitive data, you can build robust and maintainable Django applications. Whether you're working with full projects or standalone scripts, Django provides clear mechanisms for managing configuration safely and effectively.
Written & researched by Dr. Shahin Siami