Settings¶

Warning

Be careful when you override settings, especially when the default value is a non-empty list or dictionary, such as STATICFILES_FINDERS. Make sure you keep the components required by the features of Django you wish 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 index of the core settings. For introductory material, see the settings topic guide.

`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),
}

The model name used in this setting should be all lowercase, 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 AdminEmailHandler is configured in LOGGING (done by default), Django emails these people 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', '[email protected]'), ('Mary', '[email protected]')]

`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 HTTP Host header attacks, which are 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 request’s 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).

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 and ALLOWED_HOSTS is empty, the host is 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 you 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 doesn’t 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 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 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 doesn’t ship with Django by setting 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.

See the cache documentation for more information.

`KEY_PREFIX`¶

Default: '' (Empty string)

A string that will be automatically included (prepended by default) to all 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 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 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 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.

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 cache middleware. This prefix is combined with the KEY_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_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 it in the session is common practice in other web frameworks and therefore sometimes demanded by security auditors.

Since the default error views require the CSRF token, SessionMiddleware must appear in MIDDLEWARE before any middleware that may raise an exception to trigger 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 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. It should return an HttpResponseForbidden.

django.views.csrf.csrf_failure() accepts an additional template_name parameter that defaults to '403_csrf.html'. If a template with that name exists, 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 from the server is normalized by converting all characters to uppercase, replacing any hyphens with underscores, and adding an 'HTTP_' prefix to the name. For example, if your client sends a 'X-XSRF-TOKEN' header, the setting should 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 unsafe request, Django’s CSRF protection requires that the request have a Referer header that matches the origin present in the Host header. This prevents, for example, a POST request from subdomain.example.com from succeeding against api.example.com. If you need cross-origin unsafe requests over HTTPS, continuing the example, add "subdomain.example.com" to this list. The setting also supports subdomains, so you could add ".example.com", for example, to allow access from all subdomains of example.com.

`DATABASES`¶

Default: {} (Empty dictionary)

A dictionary containing the settings for all databases to be used with Django. It is a nested dictionary whose contents map a database alias 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 setting below on how to specify other 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 complex configurations are available:

`ATOMIC_REQUESTS`¶

Default: False

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

`AUTOCOMMIT`¶

Default: True

Set this to False if you want to disable Django’s 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'
'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 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 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, then this value is assumed to be the host.

If you’re 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, it’s 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 — Django’s 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 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 the default 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 of the DATABASES setting accepts the same values as the general TIME_ZONE setting.

This allows interacting with third-party databases that store datetimes in local time rather than UTC. To avoid issues around DST changes, you shouldn’t set 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 time according 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 with QuerySet.iterator(). Transaction pooling and server-side cursors describes 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 the creation 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 this string is passed directly through to the database, so its format is backend-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 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. See the documentation on controlling the creation order of test databases for details.

`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. See the documentation on testing 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, the tests will use a memory resident database. For all other database engines the test 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 the database into an in-memory JSON string before running tests (used to restore the database state between tests if you don’t have transactions). You can set this to False to speed up creation time if you don’t have any test classes with serialized_rollback=True.

`TEMPLATE`¶

This is a PostgreSQL-specific setting.

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