Appendix D: Settings-Mastering Django: Core

Your Django settings file contains all the configuration of your Django installation. This appendix explains how settings work and which settings are available.

- Whats a Settings File?
  - Default Settings
  - Seeing which settings youve changed
- Using settings in Python code
Altering settings at runtime

Security Creating your own settings Designating the Settings: DJANGO_SETTINGS_MODULE The django-admin utility On the server (mod_wsgi)Using Settings Without Setting DJANGO_SETTINGS_MODULE Custom default settings Either configure() or DJANGO_SETTINGS_MODULE is required Available Settings Core settings ABSOLUTE_URL_OVERRIDES ADMINS ALLOWED_HOSTS APPEND_SLASH CACHES CACHE_MIDDLEWARE_ALIAS CACHE_MIDDLEWARE_KEY_PREFIX CACHE_MIDDLEWARE_SECONDS CSRF_COOKIE_AGE CSRF_COOKIE_DOMAIN CSRF_COOKIE_HTTPONLY CSRF_COOKIE_NAME CSRF_COOKIE_PATH CSRF_COOKIE_SECURE CSRF_FAILURE_VIEW DATABASES DATABASE_ROUTERS DATE_FORMAT DATE_INPUT_FORMATS DATETIME_FORMAT DATETIME_INPUT_FORMATS DEBUG DEBUG_PROPAGATE_EXCEPTIONS DECIMAL_SEPARATOR DEFAULT_CHARSET DEFAULT_CONTENT_TYPE DEFAULT_EXCEPTION_REPORTER_FILTER DEFAULT_FILE_STORAGE DEFAULT_FROM_EMAIL DEFAULT_INDEX_TABLESPACE DEFAULT_TABLESPACE DISALLOWED_USER_AGENTS EMAIL_BACKEND EMAIL_HOST EMAIL_HOST_PASSWORD EMAIL_HOST_USER EMAIL_PORT EMAIL_SUBJECT_PREFIX EMAIL_USE_TLS EMAIL_USE_SSL EMAIL_SSL_CERTFILE EMAIL_SSL_KEYFILE EMAIL_TIMEOUT FILE_CHARSET FILE_UPLOAD_HANDLERS FILE_UPLOAD_MAX_MEMORY_SIZE FILE_UPLOAD_DIRECTORY_PERMISSIONS FILE_UPLOAD_PERMISSIONS FILE_UPLOAD_TEMP_DIR FIRST_DAY_OF_WEEK FIXTURE_DIRS FORCE_SCRIPT_NAME FORMAT_MODULE_PATH IGNORABLE_404_URLS INSTALLED_APPS INTERNAL_IPS LANGUAGE_CODE LANGUAGE_COOKIE_AGE LANGUAGE_COOKIE_DOMAIN LANGUAGE_COOKIE_NAME LANGUAGES LOCALE_PATHS LOGGING LOGGING_CONFIG MANAGERS MEDIA_ROOT MEDIA_URL MIDDLEWARE_CLASSES MIGRATION_MODULES MONTH_DAY_FORMAT NUMBER_GROUPING PREPEND_WWW ROOT_URLCONF SECRET_KEY SECURE_BROWSER_XSS_FILTER SECURE_CONTENT_TYPE_NOSNIFF SECURE_HSTS_INCLUDE_SUBDOMAINS SECURE_HSTS_SECONDS SECURE_PROXY_SSL_HEADER SECURE_REDIRECT_EXEMPT SECURE_SSL_HOST SECURE_SSL_REDIRECT SERIALIZATION_MODULES SERVER_EMAIL SHORT_DATE_FORMAT SHORT_DATETIME_FORMAT SIGNING_BACKEND SILENCED_SYSTEM_CHECKS TEMPLATES TEMPLATE_DEBUG TEST_RUNNER TEST_NON_SERIALIZED_APPS THOUSAND_SEPARATOR TIME_FORMAT TIME_INPUT_FORMATS TIME_ZONE USE_ETAGS USE_I18N USE_L10N USE_THOUSAND_SEPARATOR USE_TZ USE_X_FORWARDED_HOST WSGI_APPLICATION YEAR_MONTH_FORMAT X_FRAME_OPTIONS Auth AUTHENTICATION_BACKENDS AUTH_USER_MODEL LOGIN_REDIRECT_URL LOGIN_URL LOGOUT_URL PASSWORD_RESET_TIMEOUT_DAYS PASSWORD_HASHERS Messages MESSAGE_LEVEL MESSAGE_STORAGE MESSAGE_TAGS Sessions SESSION_CACHE_ALIAS SESSION_COOKIE_AGE SESSION_COOKIE_DOMAIN SESSION_COOKIE_HTTPONLY SESSION_COOKIE_NAME SESSION_COOKIE_PATH SESSION_COOKIE_SECURE SESSION_ENGINE SESSION_EXPIRE_AT_BROWSER_CLOSE SESSION_FILE_PATH SESSION_SAVE_EVERY_REQUEST SESSION_SERIALIZER Sites SITE_ID Static files STATIC_ROOT STATIC_URL STATICFILES_DIRS STATICFILES_STORAGE STATICFILES_FINDERS

Whats a Settings File?

A settings file is just a Python module with module-level variables.

Here are a couple of example settings:

ALLOWED_HOSTS = ["www.example.com"]
DEBUG = False
DEFAULT_FROM_EMAIL = "webmaster@example.com"

Note

If you set DEBUG to False, you also need to properly set the ALLOWED_HOSTS setting.

Because a settings file is a Python module, the following apply:

It doesnt allow for Python syntax errors.
It can assign settings dynamically using normal Python syntax. For example:
```
MY_SETTING = [str(i) for i in range(30)]
```
It can import values from other settings files.

Default Settings

A Django settings file doesnt have to define any settings if it doesnt need to. Each setting has a sensible default value. These defaults live in the module django/conf/global_settings.py.

Heres the algorithm Django uses in compiling settings:

Load settings from global_settings.py.
Load settings from the specified settings file, overriding the global settings as necessary.

Note that a settings file should not import from global_settings, because thats redundant.

Seeing which settings youve changed

Theres an easy way to view which of your settings deviate from the default settings. The command pythonmanage.py diffsettings displays differences between the current settings file and Djangos default settings.

For more, see the diffsettings documentation.

Using settings in Python code

In your Django apps, use settings by importing the object django.conf.settings. Example:

from django.conf import settings

if settings.DEBUG:
    # Do something

Note that django.conf.settings isnt a module its an object. So importing individual settings is not possible:

from django.conf.settings import DEBUG  # This won"t work.

Also note that your code should not import from either global_settings or your own settings file.django.conf.settings abstracts the concepts of default settings and site-specific settings; it presents a single interface. It also decouples the code that uses settings from the location of your settings.

Altering settings at runtime

You shouldnt alter settings in your applications at runtime. For example, dont do this in a view:

from django.conf import settings

settings.DEBUG = True   # Don"t do this!

The only place you should assign to settings is in a settings file.

Security

Because a settings file contains sensitive information, such as the database password, you should make every attempt to limit access to it. For example, change its file permissions so that only you and your Web servers user can read it. This is especially important in a shared-hosting environment.

Creating your own settings

Theres nothing stopping you from creating your own settings, for your own Django apps. Just follow these conventions:

Setting names are in all uppercase.
Dont reinvent an already-existing setting.

For settings that are sequences, Django itself uses tuples, rather than lists, but this is only a convention.

Designating the Settings: DJANGO_SETTINGS_MODULE

When you use Django, you have to tell it which settings youre using. Do this by using an environment variable, DJANGO_SETTINGS_MODULE.

The value of DJANGO_SETTINGS_MODULE should be in Python path syntax, e.g. mysite.settings.

The django-admin utility

When using django-admin, you can either set the environment variable once, or explicitly pass in the settings module each time you run the utility.

Example (Unix Bash shell):

export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

Example (Windows shell):

set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

Use the --settings command-line argument to specify the settings manually:

django-admin runserver --settings=mysite.settings

On the server (mod_wsgi)

In your live server environment, youll need to tell your WSGI application what settings file to use. Do that with os.environ:

import os

os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"

Read Chapter 22 for more information and other common elements to a Django WSGI application.

Using Settings Without Setting DJANGO_SETTINGS_MODULE

In some cases, you might want to bypass the DJANGO_SETTINGS_MODULE environment variable. For example, if youre using the template system by itself, you likely dont want to have to set up an environment variable pointing to a settings module.

In these cases, you can configure Djangos settings manually. Do this by calling:

django.conf.settings.configure(default_settings, **settings)

Example:

from django.conf import settings

settings.configure(DEBUG=True, TEMPLATE_DEBUG=True)

Pass configure() as many keyword arguments as youd like, with each keyword argument representing a setting and its value. Each argument name should be all uppercase, with the same name as the settings described above. If a particular setting is not passed to configure() and is needed at some later point, Django will use the default setting value.

Configuring Django in this fashion is mostly necessary and, indeed, recommended when youre using a piece of the framework inside a larger application.

Consequently, when configured via settings.configure(), Django will not make any modifications to the process environment variables (see the documentation of TIME_ZONE for why this would normally occur). Its assumed that youre already in full control of your environment in these cases.

Custom default settings

If youd like default values to come from somewhere other than django.conf.global_settings, you can pass in a module or class that provides the default settings as the default_settings argument (or as the first positional argument) in the call to configure().

In this example, default settings are taken from myapp_defaults, and the DEBUG setting is set to True, regardless of its value in myapp_defaults:

from django.conf import settings
from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)

The following example, which uses myapp_defaults as a positional argument, is equivalent:

settings.configure(myapp_defaults, DEBUG=True)

Normally, you will not need to override the defaults in this fashion. The Django defaults are sufficiently tame that you can safely use them. Be aware that if you do pass in a new default module, it entirelyreplaces the Django defaults, so you must specify a value for every possible setting that might be used in that code you are importing. Check in django.conf.settings.global_settings for the full list.

Either configure() or DJANGO_SETTINGS_MODULE is required

If youre not setting the DJANGO_SETTINGS_MODULE environment variable, you must call configure() at some point before using any code that reads settings.

If you dont set DJANGO_SETTINGS_MODULE and dont call configure(), Django will raise an ImportError exception the first time a setting is accessed.

If you set DJANGO_SETTINGS_MODULE, access settings values somehow, then call configure(), Django will raise aRuntimeError indicating that settings have already been configured. There is a property just for this purpose:

django.conf.settings.configured

For example:

from django.conf import settings
if not settings.configured:
    settings.configure(myapp_defaults, DEBUG=True)

Also, its an error to call configure() more than once, or to call configure() after any setting has been accessed.

It boils down to this: Use exactly one of either configure() or DJANGO_SETTINGS_MODULE. Not both, and not neither.

Available Settings

Warning

Be careful when you override settings, especially when the default value is a non-empty list or dictionary, such as MIDDLEWARE_CLASSES and STATICFILES_FINDERS. Make sure you keep the components required by the features of Django you wish to use.

Core settings

Heres a list of settings available in Django core and their default values. Settings provided by contrib apps are listed below, followed by a topical index of the core settings.

ABSOLUTE_URL_OVERRIDES

Default: {} (Empty dictionary)

A dictionary mapping "app_label.model_name" strings to functions that take a model object and return its URL. This is a way of inserting or overriding get_absolute_url() methods on a per-installation basis. Example:

ABSOLUTE_URL_OVERRIDES = {
    "blogs.weblog": lambda o: "/blogs/%s/" % o.slug,
    "news.story": lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
}

Note that the model name used in this setting should be all lower-case, regardless of the case of the actual model class name.

ADMINS

Default: [] (Empty list)

A list of all the people who get code error notifications. When DEBUG=False and a view raises an exception, Django will email these people with the full exception information. Each item in the list should be a tuple of (Full name, email address). Example:

[("John", "john@example.com"), ("Mary", "mary@example.com")]

Note that Django will email all of these people whenever an error happens.

ALLOWED_HOSTS

Default: [] (Empty list)

A list of strings representing the host/domain names that this Django site can serve. This is a security measure to prevent an attacker from poisoning caches and password reset emails with links to malicious hosts by submitting requests with a fake HTTP Host header, which is possible even under many seemingly-safe web server configurations.

Values in this list can be fully qualified names (e.g. "www.example.com"), in which case they will be matched against the requests Host header exactly (case-insensitive, not including port). A value beginning with a period can be used as a subdomain wildcard: ".example.com" will match example.com, www.example.com, and any other subdomain of example.com. A value of "*" will match anything; in this case you are responsible to provide your own validation of the Host header (perhaps in a middleware; if so this middleware must be listed first in MIDDLEWARE_CLASSES).

Django also allows the fully qualified domain name (FQDN) of any entries. Some browsers include a trailing dot in the Host header which Django strips when performing host validation.

If the Host header (or X-Forwarded-Host if USE_X_FORWARDED_HOST is enabled) does not match any value in this list, the django.http.HttpRequest.get_host() method will raise SuspiciousOperation.

When DEBUG is True or when running tests, host validation is disabled; any host will be accepted. Thus its usually only necessary to set it in production.

This validation only applies via get_host(); if your code accesses the Host header directly from request.METAyou are bypassing this security protection.

APPEND_SLASH

Default: True

When set to True, if the request URL does not match any of the patterns in the URLconf and it doesnt end in a slash, an HTTP redirect is issued to the same URL with a slash appended. Note that the redirect may cause any data submitted in a POST request to be lost.

The APPEND_SLASH setting is only used if CommonMiddleware is installed . See also PREPEND_WWW.

CACHES

Default:

{
    "default": {
        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
    }
}

A dictionary containing the settings for all caches to be used with Django. It is a nested dictionary whose contents maps cache aliases to a dictionary containing the options for an individual cache.

The CACHES setting must configure a default cache; any number of additional caches may also be specified. If you are using a cache backend other than the local memory cache, or you need to define multiple caches, other options will be required. The following cache options are available.

BACKEND

Default: "" (Empty string)

The cache backend to use. The built-in cache backends are:

"django.core.cache.backends.db.DatabaseCache"
"django.core.cache.backends.dummy.DummyCache"
"django.core.cache.backends.filebased.FileBasedCache"
"django.core.cache.backends.locmem.LocMemCache"
"django.core.cache.backends.memcached.MemcachedCache"
"django.core.cache.backends.memcached.PyLibMCCache"

You can use a cache backend that doesnt ship with Django by setting BACKEND <CACHES-BACKEND> to a fully-qualified path of a cache backend class (i.e. mypackage.backends.whatever.WhateverCache).

KEY_FUNCTION

A string containing a dotted path to a function (or any callable) that defines how to compose a prefix, version and key into a final cache key. The default implementation is equivalent to the function:

def make_key(key, key_prefix, version):
    return ":".join([key_prefix, str(version), key])

You may use any key function you want, as long as it has the same argument signature.

KEY_PREFIX

Default: "" (Empty string)

A string that will be automatically included (prepended by default) to all cache keys used by the Django server.

LOCATION

Default: "" (Empty string)

The location of the cache to use. This might be the directory for a file system cache, a host and port for a memcache server, or simply an identifying name for a local memory cache. e.g.:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "/var/tmp/django_cache",
    }
}

OPTIONS

Default: None

Extra parameters to pass to the cache backend. Available parameters vary depending on your cache backend.

Some information on available parameters can be found in the Cache Backends documentation. For more information, consult your backend modules own documentation.

TIMEOUT

Default: 300

The number of seconds before a cache entry is considered stale. If the value of this settings is None, cache entries will not expire.

VERSION

Default: 1

The default version number for cache keys generated by the Django server.

CACHE_MIDDLEWARE_ALIAS

Default: default

The cache connection to use for the cache middleware.

CACHE_MIDDLEWARE_KEY_PREFIX

Default: "" (Empty string)

A string which will be prefixed to the cache keys generated by the cache middleware. This prefix is combined with the KEY_PREFIX <CACHES-KEY_PREFIX> setting; it does not replace it.

See Chapter 17 for more information on caching in Django.

CACHE_MIDDLEWARE_SECONDS

Default: 600

The default number of seconds to cache a page for the cache middleware.

See Chapter 17 for more information on caching in Django.

CSRF_COOKIE_AGE

Default: 31449600 (1 year, in seconds)

The age of CSRF cookies, in seconds.

The reason for setting a long-lived expiration time is to avoid problems in the case of a user closing a browser or bookmarking a page and then loading that page from a browser cache. Without persistent cookies, the form submission would fail in this case.

Some browsers (specifically Internet Explorer) can disallow the use of persistent cookies or can have the indexes to the cookie jar corrupted on disk, thereby causing CSRF protection checks to fail (and sometimes intermittently). Change this setting to None to use session-based CSRF cookies, which keep the cookies in-memory instead of on persistent storage.

CSRF_COOKIE_DOMAIN

Default: None

The domain to be used when setting the CSRF cookie. This can be useful for easily allowing cross-subdomain requests to be excluded from the normal cross site request forgery protection. It should be set to a string such as ".example.com" to allow a POST request from a form on one subdomain to be accepted by a view served from another subdomain.

Please note that the presence of this setting does not imply that Djangos CSRF protection is safe from cross-subdomain attacks by default – please see the CSRF limitations section.

CSRF_COOKIE_HTTPONLY

Default: False

Whether to use HttpOnly flag on the CSRF cookie. If this is set to True, client-side JavaScript will not to be able to access the CSRF cookie.

This can help prevent malicious JavaScript from bypassing CSRF protection. If you enable this and need to send the value of the CSRF token with Ajax requests, your JavaScript will need to pull the value from a hidden CSRF token form input on the page instead of from the cookie.

See SESSION_COOKIE_HTTPONLY for details on HttpOnly.

CSRF_COOKIE_NAME

Default: "csrftoken"

The name of the cookie to use for the CSRF authentication token. This can be whatever you want.

CSRF_COOKIE_PATH

Default: "/"

The path set on the CSRF cookie. This should either match the URL path of your Django installation or be a parent of that path.

This is useful if you have multiple Django instances running under the same hostname. They can use different cookie paths, and each instance will only see its own CSRF cookie.

CSRF_COOKIE_SECURE

Default: False

Whether to use a secure cookie for the CSRF cookie. If this is set to True, the cookie will be marked as secure, which means browsers may ensure that the cookie is only sent under an HTTPS connection.

CSRF_FAILURE_VIEW

Default: "django.views.csrf.csrf_failure"

A dotted path to the view function to be used when an incoming request is rejected by the CSRF protection. The function should have this signature:

def csrf_failure(request, reason="")

where reason is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected.

DATABASES

Default: {} (Empty dictionary)

A dictionary containing the settings for all databases to be used with Django. It is a nested dictionary whose contents maps database aliases to a dictionary containing the options for an individual database.

The DATABASES setting must configure a default database; any number of additional databases may also be specified.

The simplest possible settings file is for a single-database setup using SQLite. This can be configured using the following:

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

When connecting to other database backends, such as MySQL, Oracle, or PostgreSQL, additional connection parameters will be required. See the ENGINE <DATABASE-ENGINE> setting below on how to specify other database types. This example is for PostgreSQL:

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql_psycopg2",
        "NAME": "mydatabase",
        "USER": "mydatabaseuser",
        "PASSWORD": "mypassword",
        "HOST": "127.0.0.1",
        "PORT": "5432",
    }
}

The following inner options that may be required for more complex configurations are available:

ATOMIC_REQUESTS

Default: False

Set this to True to wrap each HTTP request in a transaction on this database.

AUTOCOMMIT

Default: True

Set this to False if you want to disable Djangos transaction management and implement your own.

ENGINE

Default: "" (Empty string)

The database backend to use. The built-in database backends are:

"django.db.backends.postgresql_psycopg2"
"django.db.backends.mysql"
"django.db.backends.sqlite3"
"django.db.backends.oracle"

You can use a database backend that doesnt ship with Django by setting ENGINE to a fully-qualified path (i.e. mypackage.backends.whatever).

HOST

Default: "" (Empty string)

Which host to use when connecting to the database. An empty string means localhost. Not used with SQLite.

If this value starts with a forward slash ("/") and youre using MySQL, MySQL will connect via a Unix socket to the specified socket. For example:

"HOST": "/var/run/mysql"

If youre using MySQL and this value doesnt start with a forward slash, then this value is assumed to be the host.

If youre using PostgreSQL, by default (empty HOST), the connection to the database is done through UNIX domain sockets (local lines in pg_hba.conf). If your UNIX domain socket is not in the standard location, use the same value of unix_socket_directory from postgresql.conf. If you want to connect through TCP sockets, set HOST to localhost or 127.0.0.1 (host lines in pg_hba.conf). On Windows, you should always define HOST, as UNIX domain sockets are not available.

NAME

Default: "" (Empty string)

The name of the database to use. For SQLite, its the full path to the database file. When specifying the path, always use forward slashes, even on Windows (e.g. C:/homes/user/mysite/sqlite3.db).

CONN_MAX_AGE

Default: 0

The lifetime of a database connection, in seconds. Use 0 to close database connections at the end of each request Djangos historical behavior and None for unlimited persistent connections.

OPTIONS

Default: {} (Empty dictionary)

Extra parameters to use when connecting to the database. Available parameters vary depending on your database backend.

Some information on available parameters can be found in the Database Backends documentation. For more information, consult your backend modules own documentation.

PASSWORD

Default: "" (Empty string)

The password to use when connecting to the database. Not used with SQLite.

PORT

Default: "" (Empty string)

The port to use when connecting to the database. An empty string means the default port. Not used with SQLite.

USER

Default: "" (Empty string)

The username to use when connecting to the database. Not used with SQLite.

TEST

Default: {}

A dictionary of settings for test databases. The following entries are available:

CHARSET

Default: None

The character set encoding used to create the test database. The value of this string is passed directly through to the database, so its format is backend-specific.

Supported for the PostgreSQL (postgresql_psycopg2) and MySQL (mysql) backends.

COLLATION

Default: None

The collation order to use when creating the test database. This value is passed directly to the backend, so its format is backend-specific.

Only supported for the mysql backend (see the MySQL manual for details).

DEPENDENCIES

Default: ["default"], for all databases other than default, which has no dependencies.

The creation-order dependencies of the database. MIRROR ^^^^^^

Default: None

The alias of the database that this database should mirror during testing.

This setting exists to allow for testing of primary/replica (referred to as master/slave by some databases) configurations of multiple databases.

NAME

Default: None

The name of database to use when running the test suite.

If the default value (None) is used with the SQLite database engine, the tests will use a memory resident database. For all other database engines the test database will use the name "test_" + DATABASE_NAME.

SERIALIZE

Boolean value to control whether or not the default test runner serializes the database into an in-memory JSON string before running tests (used to restore the database state between tests if you dont have transactions). You can set this to False to speed up creation time if you dont have any test classes with serialized_rollback=True.