Settings

Settings

Warning

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

Core Settings

Here’s a list of settings available in Django core and their default values.Settings provided by contrib apps are listed below, followed by a topical indexof the core settings. For introductory material, see the settings topicguide.

ABSOLUTE_URL_OVERRIDES

Default: {} (Empty dictionary)

A dictionary mapping "app_label.model_name" strings to functions that takea model object and return its URL. This is a way of inserting or overridingget_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),
}

The model name used in this setting should be all lowercase, regardless of thecase of the actual model class name.

ADMINS

Default: [] (Empty list)

A list of all the people who get code error notifications. WhenDEBUG=False and AdminEmailHandleris configured in LOGGING (done by default), Django emails thesepeople the details of exceptions raised in the request/response cycle.

Each item in the list should be a tuple of (Full name, email address). Example:

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

ALLOWED_HOSTS

Default: [] (Empty list)

A list of strings representing the host/domain names that this Django site canserve. This is a security measure to prevent HTTP Host header attacks, which are possible even under manyseemingly-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 request’s Host headerexactly (case-insensitive, not including port). A value beginning with a periodcan be used as a subdomain wildcard: '.example.com' will matchexample.com, www.example.com, and any other subdomain ofexample.com. A value of '*' will match anything; in this case you areresponsible to provide your own validation of the Host header (perhaps in amiddleware; if so this middleware must be listed first inMIDDLEWARE).

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

If the Host header (or X-Forwarded-Host ifUSE_X_FORWARDED_HOST is enabled) does not match any value in thislist, the django.http.HttpRequest.get_host() method will raiseSuspiciousOperation.

When DEBUG is True and ALLOWED_HOSTS is empty, the hostis validated against ['localhost', '127.0.0.1', '[::1]'].

ALLOWED_HOSTS is also checked when running tests.

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

APPEND_SLASH

Default: True

When set to True, if the request URL does not match any of the patternsin the URLconf and it doesn’t end in a slash, an HTTP redirect is issued to thesame URL with a slash appended. Note that the redirect may cause any datasubmitted in a POST request to be lost.

The APPEND_SLASH setting is only used ifCommonMiddleware is installed(see Middleware). 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 withDjango. It is a nested dictionary whose contents maps cache aliasesto 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 youare using a cache backend other than the local memory cache, oryou 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 doesn’t ship with Django by settingBACKEND to a fully-qualified path of a cachebackend class (i.e. mypackage.backends.whatever.WhateverCache).

KEY_FUNCTION

A string containing a dotted path to a function (or any callable) that defines how tocompose a prefix, version and key into a final cache key. The defaultimplementation 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 sameargument signature.

See the cache documentation for moreinformation.

KEY_PREFIX

Default: '' (Empty string)

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

See the cache documentation for more information.

LOCATION

Default: '' (Empty string)

The location of the cache to use. This might be the directory for afile system cache, a host and port for a memcache server, or an identifyingname 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 parametersvary depending on your cache backend.

Some information on available parameters can be found in thecache arguments documentation. For more information,consult your backend module’s own documentation.

TIMEOUT

Default: 300

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

VERSION

Default: 1

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

See the cache documentation for more information.

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 cachemiddleware. This prefix is combined with theKEY_PREFIX setting; it does not replace it.

See Django’s cache framework.

CACHE_MIDDLEWARE_SECONDS

Default: 600

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

See Django’s cache framework.

CSRF_COOKIE_AGE

Default: 31449600 (approximately 1 year, in seconds)

The age of CSRF cookies, in seconds.

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

Some browsers (specifically Internet Explorer) can disallow the use ofpersistent cookies or can have the indexes to the cookie jar corrupted on disk,thereby causing CSRF protection checks to (sometimes intermittently) fail.Change this setting to None to use session-based CSRF cookies, whichkeep 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 foreasily allowing cross-subdomain requests to be excluded from the normal crosssite 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 beaccepted by a view served from another subdomain.

Please note that the presence of this setting does not imply that Django’s CSRFprotection is safe from cross-subdomain attacks by default - please see theCSRF limitations section.

CSRF_COOKIE_HTTPONLY

Default: False

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

Designating the CSRF cookie as HttpOnly doesn’t offer any practicalprotection because CSRF is only to protect against cross-domain attacks. If anattacker can read the cookie via JavaScript, they’re already on the same domainas far as the browser knows, so they can do anything they like anyway. (XSS isa much bigger hole than CSRF.)

Although the setting offers little practical benefit, it’s sometimes requiredby security auditors.

If you enable this and need to send the value of the CSRF token with an AJAXrequest, your JavaScript must pull the value from a hidden CSRF tokenform input 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 bewhatever you want (as long as it’s different from the other cookie names inyour application). See Cross Site Request Forgery protection.

CSRF_COOKIE_PATH

Default: '/'

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

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

CSRF_COOKIE_SAMESITE

Default: 'Lax'

The value of the SameSite flag on the CSRF cookie. This flag prevents thecookie from being sent in cross-site requests.

See SESSION_COOKIE_SAMESITE for details about SameSite.

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 thecookie is only sent with an HTTPS connection.

CSRF_USE_SESSIONS

Default: False

Whether to store the CSRF token in the user’s session instead of in a cookie.It requires the use of django.contrib.sessions.

Storing the CSRF token in a cookie (Django’s default) is safe, but storing itin the session is common practice in other web frameworks and thereforesometimes demanded by security auditors.

Since the default error views require the CSRF token,SessionMiddleware must appear inMIDDLEWARE before any middleware that may raise an exception totrigger an error view (such as PermissionDenied)if you’re using CSRF_USE_SESSIONS. See Middleware ordering.

CSRF_FAILURE_VIEW

Default: 'django.views.csrf.csrf_failure'

A dotted path to the view function to be used when an incoming request isrejected by the CSRF protection. The function should havethis signature:

def csrf_failure(request, reason=""):
    ...

where reason is a short message (intended for developers or logging, notfor end users) indicating the reason the request was rejected. It should returnan HttpResponseForbidden.

django.views.csrf.csrf_failure() accepts an additional template_nameparameter that defaults to '403_csrf.html'. If a template with that nameexists, it will be used to render the page.

CSRF_HEADER_NAME

Default: 'HTTP_X_CSRFTOKEN'

The name of the request header used for CSRF authentication.

As with other HTTP headers in request.META, the header name received fromthe server is normalized by converting all characters to uppercase, replacingany hyphens with underscores, and adding an 'HTTP_' prefix to the name.For example, if your client sends a 'X-XSRF-TOKEN' header, the settingshould be 'HTTP_X_XSRF_TOKEN'.

CSRF_TRUSTED_ORIGINS

Default: [] (Empty list)

A list of hosts which are trusted origins for unsafe requests (e.g. POST).For a secure unsaferequest, Django’s CSRF protection requires that the request have a Refererheader that matches the origin present in the Host header. This prevents,for example, a POST request from subdomain.example.com from succeedingagainst api.example.com. If you need cross-origin unsafe requests overHTTPS, continuing the example, add "subdomain.example.com" to this list.The setting also supports subdomains, so you could add ".example.com", forexample, to allow access from all subdomains of example.com.

DATABASES

Default: {} (Empty dictionary)

A dictionary containing the settings for all databases to be used withDjango. It is a nested dictionary whose contents map a database aliasto 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 usingSQLite. This can be configured using the following:

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

When connecting to other database backends, such as MariaDB, MySQL, Oracle, orPostgreSQL, additional connection parameters will be required. Seethe ENGINE setting below on how to specifyother database types. This example is for PostgreSQL:

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

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

ATOMIC_REQUESTS

Default: False

Set this to True to wrap each view in a transaction on this database. SeeTying transactions to HTTP requests.

AUTOCOMMIT

Default: True

Set this to False if you want to disable Django’s transactionmanagement and implement your own.

ENGINE

Default: '' (Empty string)

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

'django.db.backends.postgresql'
'django.db.backends.mysql'
'django.db.backends.sqlite3'
'django.db.backends.oracle'You can use a database backend that doesn’t ship with Django by settingENGINE 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 meanslocalhost. Not used with SQLite.

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

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

If you’re using MySQL and this value doesn’t start with a forward slash, thenthis value is assumed to be the host.

If you’re using PostgreSQL, by default (empty HOST), the connectionto the database is done through UNIX domain sockets (‘local’ lines inpg_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 socketsare not available.

NAME

Default: '' (Empty string)

The name of the database to use. For SQLite, it’s the full path to the databasefile. 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 databaseconnections at the end of each request — Django’s historical behavior — andNone for unlimited persistent connections.

OPTIONS

Default: {} (Empty dictionary)

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

Some information on available parameters can be found in theDatabase Backends documentation. For more information,consult your backend module’s 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 thedefault port. Not used with SQLite.

TIME_ZONE

Default: None

A string representing the time zone for datetimes stored in this database(assuming that it doesn’t support time zones) or None. This inner option ofthe DATABASES setting accepts the same values as the generalTIME_ZONE setting.

This allows interacting with third-party databases that store datetimes inlocal time rather than UTC. To avoid issues around DST changes, you shouldn’tset this option for databases managed by Django.

When USE_TZ is True and the database doesn’t support time zones(e.g. SQLite, MySQL, Oracle), Django reads and writes datetimes in local timeaccording to this option if it is set and in UTC if it isn’t.

When USE_TZ is True and the database supports time zones (e.g.PostgreSQL), it is an error to set this option.

When USE_TZ is False, it is an error to set this option.

DISABLE_SERVER_SIDE_CURSORS

Default: False

Set this to True if you want to disable the use of server-side cursors withQuerySet.iterator(). Transaction pooling and server-side cursorsdescribes the use case.

This is a PostgreSQL-specific setting.

USER

Default: '' (Empty string)

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

TEST

Default: {} (Empty dictionary)

A dictionary of settings for test databases; for more details about thecreation and use of test databases, see The test database.

Here’s an example with a test database configuration:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'USER': 'mydatabaseuser',
        'NAME': 'mydatabase',
        'TEST': {
            'NAME': 'mytestdatabase',
        },
    },
}

The following keys in the TEST dictionary are available:

CHARSET

Default: None

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

Supported by the PostgreSQL (postgresql) and MySQL (mysql) backends.

COLLATION

Default: None

The collation order to use when creating the test database. This value ispassed 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. See the documentationon controlling the creation order of test databases for details.

MIRROR

Default: None

The alias of the database that this database should mirror duringtesting.

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

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, thetests will use a memory resident database. For all other database engines thetest database will use the name 'test_' + DATABASE_NAME.

See The test database.

SERIALIZE

Boolean value to control whether or not the default test runner serializes thedatabase into an in-memory JSON string before running tests (used to restorethe database state between tests if you don’t have transactions). You can setthis to False to speed up creation time if you don’t have any test classeswith serialized_rollback=True.

TEMPLATE

This is a PostgreSQL-specific setting.

The name of a template (e.g. 'template0') from which to create the testdatabase.