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:

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

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:

  1. [('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:

  1. {
  2. 'default': {
  3. 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
  4. }
  5. }

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:

  1. def make_key(key, key_prefix, version):
  2. 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.:

  1. CACHES = {
  2. 'default': {
  3. 'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
  4. 'LOCATION': '/var/tmp/django_cache',
  5. }
  6. }

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.

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.

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.

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.

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.

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.

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.

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:

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

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:

  1. DATABASES = {
  2. 'default': {
  3. 'ENGINE': 'django.db.backends.sqlite3',
  4. 'NAME': 'mydatabase',
  5. }
  6. }

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:

  1. DATABASES = {
  2. 'default': {
  3. 'ENGINE': 'django.db.backends.postgresql',
  4. 'NAME': 'mydatabase',
  5. 'USER': 'mydatabaseuser',
  6. 'PASSWORD': 'mypassword',
  7. 'HOST': '127.0.0.1',
  8. 'PORT': '5432',
  9. }
  10. }

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:

  1. "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:

  1. DATABASES = {
  2. 'default': {
  3. 'ENGINE': 'django.db.backends.postgresql',
  4. 'USER': 'mydatabaseuser',
  5. 'NAME': 'mydatabase',
  6. 'TEST': {
  7. 'NAME': 'mytestdatabase',
  8. },
  9. },
  10. }

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.

CREATE_DB

Default: True

This is an Oracle-specific setting.

If it is set to False, the test tablespaces won’t be automatically createdat the beginning of the tests or dropped at the end.

CREATE_USER

Default: True

This is an Oracle-specific setting.

If it is set to False, the test user won’t be automatically created at thebeginning of the tests and dropped at the end.

USER

Default: None

This is an Oracle-specific setting.

The username to use when connecting to the Oracle database that will be usedwhen running tests. If not provided, Django will use 'test_' + USER.

PASSWORD

Default: None

This is an Oracle-specific setting.

The password to use when connecting to the Oracle database that will be usedwhen running tests. If not provided, Django will generate a random password.

ORACLE_MANAGED_FILES

New in Django 2.2:

Default: False

This is an Oracle-specific setting.

If set to True, Oracle Managed Files (OMF) tablespaces will be used.DATAFILE and DATAFILE_TMP will be ignored.

TBLSPACE

Default: None

This is an Oracle-specific setting.

The name of the tablespace that will be used when running tests. If notprovided, Django will use 'test_' + USER.

TBLSPACE_TMP

Default: None

This is an Oracle-specific setting.

The name of the temporary tablespace that will be used when running tests. Ifnot provided, Django will use 'test_' + USER + '_temp'.

DATAFILE

Default: None

This is an Oracle-specific setting.

The name of the datafile to use for the TBLSPACE. If not provided, Django willuse TBLSPACE + '.dbf'.

DATAFILE_TMP

Default: None

This is an Oracle-specific setting.

The name of the datafile to use for the TBLSPACE_TMP. If not provided, Djangowill use TBLSPACE_TMP + '.dbf'.

DATAFILE_MAXSIZE

Default: '500M'

This is an Oracle-specific setting.

The maximum size that the DATAFILE is allowed to grow to.

DATAFILE_TMP_MAXSIZE

Default: '500M'

This is an Oracle-specific setting.

The maximum size that the DATAFILE_TMP is allowed to grow to.

DATAFILE_SIZE

Default: '50M'

This is an Oracle-specific setting.

The initial size of the DATAFILE.

DATAFILE_TMP_SIZE

Default: '50M'

This is an Oracle-specific setting.

The initial size of the DATAFILE_TMP.

DATAFILE_EXTSIZE

Default: '25M'

This is an Oracle-specific setting.

The amount by which the DATAFILE is extended when more space is required.

DATAFILE_TMP_EXTSIZE

Default: '25M'

This is an Oracle-specific setting.

The amount by which the DATAFILE_TMP is extended when more space is required.

DATA_UPLOAD_MAX_MEMORY_SIZE

Default: 2621440 (i.e. 2.5 MB).

The maximum size in bytes that a request body may be before aSuspiciousOperation (RequestDataTooBig) israised. The check is done when accessing request.body or request.POSTand is calculated against the total request size excluding any file uploaddata. You can set this to None to disable the check. Applications that areexpected to receive unusually large form posts should tune this setting.

The amount of request data is correlated to the amount of memory needed toprocess the request and populate the GET and POST dictionaries. Large requestscould be used as a denial-of-service attack vector if left unchecked. Since webservers don’t typically perform deep request inspection, it’s not possible toperform a similar check at that level.

See also FILE_UPLOAD_MAX_MEMORY_SIZE.

DATA_UPLOAD_MAX_NUMBER_FIELDS

Default: 1000

The maximum number of parameters that may be received via GET or POST before aSuspiciousOperation (TooManyFields) israised. You can set this to None to disable the check. Applications thatare expected to receive an unusually large number of form fields should tunethis setting.

The number of request parameters is correlated to the amount of time needed toprocess the request and populate the GET and POST dictionaries. Large requestscould be used as a denial-of-service attack vector if left unchecked. Since webservers don’t typically perform deep request inspection, it’s not possible toperform a similar check at that level.

DATABASE_ROUTERS

Default: [] (Empty list)

The list of routers that will be used to determine which databaseto use when performing a database query.

See the documentation on automatic database routing in multidatabase configurations.

DATE_FORMAT

Default: 'N j, Y' (e.g. Feb. 4, 2003)

The default formatting to use for displaying date fields in any part of thesystem. Note that if USE_L10N is set to True, then thelocale-dictated format has higher precedence and will be applied instead. Seeallowed date format strings.

See also DATETIME_FORMAT, TIME_FORMAT and SHORT_DATE_FORMAT.

DATE_INPUT_FORMATS

Default:

  1. [
  2. '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
  3. '%b %d %Y', '%b %d, %Y', # 'Oct 25 2006', 'Oct 25, 2006'
  4. '%d %b %Y', '%d %b, %Y', # '25 Oct 2006', '25 Oct, 2006'
  5. '%B %d %Y', '%B %d, %Y', # 'October 25 2006', 'October 25, 2006'
  6. '%d %B %Y', '%d %B, %Y', # '25 October 2006', '25 October, 2006'
  7. ]

A list of formats that will be accepted when inputting data on a date field.Formats will be tried in order, using the first valid one. Note that theseformat strings use Python’s datetime module syntax, not the format strings from the datetemplate filter.

When USE_L10N is True, the locale-dictated format has higherprecedence and will be applied instead.

See also DATETIME_INPUT_FORMATS and TIME_INPUT_FORMATS.

DATETIME_FORMAT

Default: 'N j, Y, P' (e.g. Feb. 4, 2003, 4 p.m.)

The default formatting to use for displaying datetime fields in any part of thesystem. Note that if USE_L10N is set to True, then thelocale-dictated format has higher precedence and will be applied instead. Seeallowed date format strings.

See also DATE_FORMAT, TIME_FORMAT and SHORT_DATETIME_FORMAT.

DATETIME_INPUT_FORMATS

Default:

  1. [
  2. '%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59'
  3. '%Y-%m-%d %H:%M:%S.%f', # '2006-10-25 14:30:59.000200'
  4. '%Y-%m-%d %H:%M', # '2006-10-25 14:30'
  5. '%Y-%m-%d', # '2006-10-25'
  6. '%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59'
  7. '%m/%d/%Y %H:%M:%S.%f', # '10/25/2006 14:30:59.000200'
  8. '%m/%d/%Y %H:%M', # '10/25/2006 14:30'
  9. '%m/%d/%Y', # '10/25/2006'
  10. '%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59'
  11. '%m/%d/%y %H:%M:%S.%f', # '10/25/06 14:30:59.000200'
  12. '%m/%d/%y %H:%M', # '10/25/06 14:30'
  13. '%m/%d/%y', # '10/25/06'
  14. ]

A list of formats that will be accepted when inputting data on a datetimefield. Formats will be tried in order, using the first valid one. Note thatthese format strings use Python’s datetime module syntax, not the format strings from the datetemplate filter.

When USE_L10N is True, the locale-dictated format has higherprecedence and will be applied instead.

See also DATE_INPUT_FORMATS and TIME_INPUT_FORMATS.

DEBUG

Default: False

A boolean that turns on/off debug mode.

Never deploy a site into production with DEBUG turned on.

One of the main features of debug mode is the display of detailed error pages.If your app raises an exception when DEBUG is True, Django willdisplay a detailed traceback, including a lot of metadata about yourenvironment, such as all the currently defined Django settings (fromsettings.py).

As a security measure, Django will not include settings that might besensitive, such as SECRET_KEY. Specifically, it will exclude anysetting whose name includes any of the following:

  • 'API'
  • 'KEY'
  • 'PASS'
  • 'SECRET'
  • 'SIGNATURE'
  • 'TOKEN'Note that these are partial matches. 'PASS' will also match PASSWORD,just as 'TOKEN' will also match TOKENIZED and so on.

Still, note that there are always going to be sections of your debug outputthat are inappropriate for public consumption. File paths, configurationoptions and the like all give attackers extra information about your server.

It is also important to remember that when running with DEBUGturned on, Django will remember every SQL query it executes. This is usefulwhen you’re debugging, but it’ll rapidly consume memory on a production server.

Finally, if DEBUG is False, you also need to properly setthe ALLOWED_HOSTS setting. Failing to do so will result in allrequests being returned as “Bad Request (400)”.

Note

The default settings.py file created by django-adminstartproject sets DEBUG = True for convenience.

DEBUG_PROPAGATE_EXCEPTIONS

Default: False

If set to True, Django’s exception handling of view functions(handler500, or the debug view if DEBUGis True) and logging of 500 responses (django.request) isskipped and exceptions propagate upwards.

This can be useful for some test setups. It shouldn’t be used on a live siteunless you want your web server (instead of Django) to generate “InternalServer Error” responses. In that case, make sure your server doesn’t show thestack trace or other sensitive information in the response.

DECIMAL_SEPARATOR

Default: '.' (Dot)

Default decimal separator used when formatting decimal numbers.

Note that if USE_L10N is set to True, then the locale-dictatedformat has higher precedence and will be applied instead.

See also NUMBER_GROUPING, THOUSAND_SEPARATOR andUSE_THOUSAND_SEPARATOR.

DEFAULT_CHARSET

Default: 'utf-8'

Default charset to use for all HttpResponse objects, if a MIME type isn’tmanually specified. Used when constructing the Content-Type header.

DEFAULT_EXCEPTION_REPORTER_FILTER

Default: 'django.views.debug.SafeExceptionReporterFilter'

Default exception reporter filter class to be used if none has been assigned tothe HttpRequest instance yet.See Filtering error reports.

DEFAULT_FILE_STORAGE

Default: 'django.core.files.storage.FileSystemStorage'

Default file storage class to be used for any file-related operations that don’tspecify a particular storage system. See Managing files.

DEFAULT_FROM_EMAIL

Default: 'webmaster@localhost'

Default email address to use for various automated correspondence from thesite manager(s). This doesn’t include error messages sent to ADMINSand MANAGERS; for that, see SERVER_EMAIL.

DEFAULT_INDEX_TABLESPACE

Default: '' (Empty string)

Default tablespace to use for indexes on fields that don’t specifyone, if the backend supports it (see Tablespaces).

DEFAULT_TABLESPACE

Default: '' (Empty string)

Default tablespace to use for models that don’t specify one, if thebackend supports it (see Tablespaces).

DISALLOWED_USER_AGENTS

Default: [] (Empty list)

List of compiled regular expression objects representing User-Agent stringsthat are not allowed to visit any page, systemwide. Use this for bots/crawlers.This is only used if CommonMiddleware is installed (seeMiddleware).

EMAIL_BACKEND

Default: 'django.core.mail.backends.smtp.EmailBackend'

The backend to use for sending emails. For the list of available backends seeSending email.

EMAIL_FILE_PATH

Default: Not defined

The directory used by the file email backend to store output files.

EMAIL_HOST

Default: 'localhost'

The host to use for sending email.

See also EMAIL_PORT.

EMAIL_HOST_PASSWORD

Default: '' (Empty string)

Password to use for the SMTP server defined in EMAIL_HOST. Thissetting is used in conjunction with EMAIL_HOST_USER whenauthenticating to the SMTP server. If either of these settings is empty,Django won’t attempt authentication.

See also EMAIL_HOST_USER.

EMAIL_HOST_USER

Default: '' (Empty string)

Username to use for the SMTP server defined in EMAIL_HOST.If empty, Django won’t attempt authentication.

See also EMAIL_HOST_PASSWORD.

EMAIL_PORT

Default: 25

Port to use for the SMTP server defined in EMAIL_HOST.

EMAIL_SUBJECT_PREFIX

Default: '[Django] '

Subject-line prefix for email messages sent with django.core.mail.mail_adminsor django.core.mail.mail_managers. You’ll probably want to include thetrailing space.

EMAIL_USE_LOCALTIME

Default: False

Whether to send the SMTP Date header of email messages in the local timezone (True) or in UTC (False).

EMAIL_USE_TLS

Default: False

Whether to use a TLS (secure) connection when talking to the SMTP server.This is used for explicit TLS connections, generally on port 587. If you areexperiencing hanging connections, see the implicit TLS settingEMAIL_USE_SSL.

EMAIL_USE_SSL

Default: False

Whether to use an implicit TLS (secure) connection when talking to the SMTPserver. In most email documentation this type of TLS connection is referredto as SSL. It is generally used on port 465. If you are experiencing problems,see the explicit TLS setting EMAIL_USE_TLS.

Note that EMAIL_USE_TLS/EMAIL_USE_SSL are mutuallyexclusive, so only set one of those settings to True.

EMAIL_SSL_CERTFILE

Default: None

If EMAIL_USE_SSL or EMAIL_USE_TLS is True, you canoptionally specify the path to a PEM-formatted certificate chain file to usefor the SSL connection.

EMAIL_SSL_KEYFILE

Default: None

If EMAIL_USE_SSL or EMAIL_USE_TLS is True, you canoptionally specify the path to a PEM-formatted private key file to use for theSSL connection.

Note that setting EMAIL_SSL_CERTFILE and EMAIL_SSL_KEYFILEdoesn’t result in any certificate checking. They’re passed to the underlying SSLconnection. Please refer to the documentation of Python’sssl.wrap_socket() function for details on how the certificate chainfile and private key file are handled.

EMAIL_TIMEOUT

Default: None

Specifies a timeout in seconds for blocking operations like the connectionattempt.

FILE_CHARSET

Default: 'utf-8'

The character encoding used to decode any files read from disk. This includestemplate files, static files, and translation catalogs.

Deprecated since version 2.2: This setting is deprecated. Starting with Django 3.1, files read from diskmust be UTF-8 encoded.

FILE_UPLOAD_HANDLERS

Default:

  1. [
  2. 'django.core.files.uploadhandler.MemoryFileUploadHandler',
  3. 'django.core.files.uploadhandler.TemporaryFileUploadHandler',
  4. ]

A list of handlers to use for uploading. Changing this setting allows completecustomization – even replacement – of Django’s upload process.

See Managing files for details.

FILE_UPLOAD_MAX_MEMORY_SIZE

Default: 2621440 (i.e. 2.5 MB).

The maximum size (in bytes) that an upload will be before it gets streamed tothe file system. See Managing files for details.

See also DATA_UPLOAD_MAX_MEMORY_SIZE.

FILE_UPLOAD_DIRECTORY_PERMISSIONS

Default: None

The numeric mode to apply to directories created in the process of uploadingfiles.

This setting also determines the default permissions for collected staticdirectories when using the collectstatic management command. Seecollectstatic for details on overriding it.

This value mirrors the functionality and caveats of theFILE_UPLOAD_PERMISSIONS setting.

FILE_UPLOAD_PERMISSIONS

Default: 0o644

The numeric mode (i.e. 0o644) to set newly uploaded files to. Formore information about what these modes mean, see the documentation foros.chmod().

If this isn’t given or is None, you’ll get operating-systemdependent behavior. On most platforms, temporary files will have a modeof 0o600, and files saved from memory will be saved using thesystem’s standard umask.

For security reasons, these permissions aren’t applied to the temporary filesthat are stored in FILE_UPLOAD_TEMP_DIR.

This setting also determines the default permissions for collected static fileswhen using the collectstatic management command. Seecollectstatic for details on overriding it.

Warning

Always prefix the mode with a 0.

If you’re not familiar with file modes, please note that the leading0 is very important: it indicates an octal number, which is theway that modes must be specified. If you try to use 644, you’llget totally incorrect behavior.

Changed in Django 3.0:In older versions, the default value is None.

FILE_UPLOAD_TEMP_DIR

Default: None

The directory to store data to (typically files larger thanFILE_UPLOAD_MAX_MEMORY_SIZE) temporarily while uploading files.If None, Django will use the standard temporary directory for the operatingsystem. For example, this will default to /tmp on *nix-style operatingsystems.

See Managing files for details.

FIRST_DAY_OF_WEEK

Default: 0 (Sunday)

A number representing the first day of the week. This is especially usefulwhen displaying a calendar. This value is only used when not usingformat internationalization, or when a format cannot be found for thecurrent locale.

The value must be an integer from 0 to 6, where 0 means Sunday, 1 meansMonday and so on.

FIXTURE_DIRS

Default: [] (Empty list)

List of directories searched for fixture files, in addition to thefixtures directory of each application, in search order.

Note that these paths should use Unix-style forward slashes, even on Windows.

See Providing data with fixtures and Fixture loading.

FORCE_SCRIPT_NAME

Default: None

If not None, this will be used as the value of the SCRIPT_NAMEenvironment variable in any HTTP request. This setting can be used to overridethe server-provided value of SCRIPT_NAME, which may be a rewritten versionof the preferred value or not supplied at all. It is also used bydjango.setup() to set the URL resolver script prefix outside of therequest/response cycle (e.g. in management commands and standalone scripts) togenerate correct URLs when SCRIPT_NAME is not /.

FORM_RENDERER

Default: 'django.forms.renderers.DjangoTemplates'

The class that renders form widgets. It must implement the low-levelrender API.

FORMAT_MODULE_PATH

Default: None

A full Python path to a Python package that contains custom format definitionsfor project locales. If not None, Django will check for a formats.pyfile, under the directory named as the current locale, and will use theformats defined in this file.

For example, if FORMAT_MODULE_PATH is set to mysite.formats,and current language is en (English), Django will expect a directory treelike:

  1. mysite/
  2. formats/
  3. __init__.py
  4. en/
  5. __init__.py
  6. formats.py

You can also set this setting to a list of Python paths, for example:

  1. FORMAT_MODULE_PATH = [
  2. 'mysite.formats',
  3. 'some_app.formats',
  4. ]

When Django searches for a certain format, it will go through all given Pythonpaths until it finds a module that actually defines the given format. Thismeans that formats defined in packages farther up in the list will takeprecedence over the same formats in packages farther down.

Available formats are:

IGNORABLE_404_URLS

Default: [] (Empty list)

List of compiled regular expression objects describing URLs that should beignored when reporting HTTP 404 errors via email (seeError reporting). Regular expressions are matched againstrequest's full paths (includingquery string, if any). Use this if your site does not provide a commonlyrequested file such as favicon.ico or robots.txt.

This is only used ifBrokenLinkEmailsMiddleware is enabled (seeMiddleware).

INSTALLED_APPS

Default: [] (Empty list)

A list of strings designating all applications that are enabled in thisDjango installation. Each string should be a dotted Python path to:

Use the application registry for introspection

Your code should never access INSTALLED_APPS directly. Usedjango.apps.apps instead.

Application names and labels must be unique in INSTALLED_APPS

Application names — the dotted Pythonpath to the application package — must be unique. There is no way toinclude the same application twice, short of duplicating its code underanother name.

Application labels — by default thefinal part of the name — must be unique too. For example, you can’tinclude both django.contrib.auth and myproject.auth. However, youcan relabel an application with a custom configuration that defines adifferent label.

These rules apply regardless of whether INSTALLED_APPSreferences application configuration classes or application packages.

When several applications provide different versions of the same resource(template, static file, management command, translation), the applicationlisted first in INSTALLED_APPS has precedence.

INTERNAL_IPS

Default: [] (Empty list)

A list of IP addresses, as strings, that:

  • Allow the debug() context processorto add some variables to the template context.
  • Can use the admindocs bookmarklets even ifnot logged in as a staff user.
  • Are marked as “internal” (as opposed to “EXTERNAL”) inAdminEmailHandler emails.

LANGUAGE_CODE

Default: 'en-us'

A string representing the language code for this installation. This should be instandard language ID format. For example, U.S. Englishis "en-us". See also the list of language identifiers andInternationalization and localization.

USE_I18N must be active for this setting to have any effect.

It serves two purposes:

  • If the locale middleware isn’t in use, it decides which translation is servedto all users.
  • If the locale middleware is active, it provides a fallback language in case theuser’s preferred language can’t be determined or is not supported by thewebsite. It also provides the fallback translation when a translation for agiven literal doesn’t exist for the user’s preferred language.See How Django discovers language preference for more details.

Default: None (expires at browser close)

The age of the language cookie, in seconds.

Default: None

The domain to use for the language cookie. Set this to a string such as"example.com" for cross-domain cookies, or use None for a standarddomain cookie.

Be cautious when updating this setting on a production site. If you updatethis setting to enable cross-domain cookies on a site that previously usedstandard domain cookies, existing user cookies that have the old domainwill not be updated. This will result in site users being unable to switchthe language as long as these cookies persist. The only safe and reliableoption to perform the switch is to change the language cookie namepermanently (via the LANGUAGE_COOKIE_NAME setting) and to adda middleware that copies the value from the old cookie to a new one and thendeletes the old one.

New in Django 3.0:

Default: False

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

See SESSION_COOKIE_HTTPONLY for details on HttpOnly.

Default: 'django_language'

The name of the cookie to use for the language cookie. This can be whateveryou want (as long as it’s different from the other cookie names in yourapplication). See Internationalization and localization.

Default: '/'

The path set on the language 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 language cookie.

Be cautious when updating this setting on a production site. If you update thissetting to use a deeper path than it previously used, existing user cookies thathave the old path will not be updated. This will result in site users beingunable to switch the language as long as these cookies persist. The only safeand reliable option to perform the switch is to change the language cookie namepermanently (via the LANGUAGE_COOKIE_NAME setting), and to adda middleware that copies the value from the old cookie to a new one and thendeletes the one.

New in Django 3.0:

Default: None

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

See SESSION_COOKIE_SAMESITE for details about SameSite.

New in Django 3.0:

Default: False

Whether to use a secure cookie for the language cookie. If this is set toTrue, the cookie will be marked as “secure”, which means browsers mayensure that the cookie is only sent under an HTTPS connection.

LANGUAGES

Default: A list of all available languages. This list is continually growingand including a copy here would inevitably become rapidly out of date. You cansee the current list of translated languages by looking indjango/conf/global_settings.py.

The list is a list of two-tuples in the format(language code, language name) – for example,('ja', 'Japanese').This specifies which languages are available for language selection. SeeInternationalization and localization.

Generally, the default value should suffice. Only set this setting if you wantto restrict language selection to a subset of the Django-provided languages.

If you define a custom LANGUAGES setting, you can mark thelanguage names as translation strings using thegettext_lazy() function.

Here’s a sample settings file:

  1. from django.utils.translation import gettext_lazy as _
  2.  
  3. LANGUAGES = [
  4. ('de', _('German')),
  5. ('en', _('English')),
  6. ]

LANGUAGES_BIDI

Default: A list of all language codes that are written right-to-left. You cansee the current list of these languages by looking indjango/conf/global_settings.py.

The list contains language codes for languages that arewritten right-to-left.

Generally, the default value should suffice. Only set this setting if you wantto restrict language selection to a subset of the Django-provided languages.If you define a custom LANGUAGES setting, the list of bidirectionallanguages may contain language codes which are not enabled on a given site.

LOCALE_PATHS

Default: [] (Empty list)

A list of directories where Django looks for translation files.See How Django discovers translations.

Example:

  1. LOCALE_PATHS = [
  2. '/home/www/project/common_files/locale',
  3. '/var/local/translations/locale',
  4. ]

Django will look within each of these paths for the <locale_code>/LC_MESSAGESdirectories containing the actual translation files.

LOGGING

Default: A logging configuration dictionary.

A data structure containing configuration information. The contents ofthis data structure will be passed as the argument to theconfiguration method described in LOGGING_CONFIG.

Among other things, the default logging configuration passes HTTP 500 servererrors to an email log handler when DEBUG is False. See alsoConfiguring logging.

You can see the default logging configuration by looking indjango/utils/log.py.

LOGGING_CONFIG

Default: 'logging.config.dictConfig'

A path to a callable that will be used to configure logging in theDjango project. Points at an instance of Python’s dictConfig configuration method by default.

If you set LOGGING_CONFIG to None, the loggingconfiguration process will be skipped.

MANAGERS

Default: [] (Empty list)

A list in the same format as ADMINS that specifies who should getbroken link notifications whenBrokenLinkEmailsMiddleware is enabled.

MEDIA_ROOT

Default: '' (Empty string)

Absolute filesystem path to the directory that will hold user-uploadedfiles.

Example: "/var/www/example.com/media/"

See also MEDIA_URL.

Warning

MEDIA_ROOT and STATIC_ROOT must have differentvalues. Before STATIC_ROOT was introduced, it was common torely or fallback on MEDIA_ROOT to also serve static files;however, since this can have serious security implications, there is avalidation check to prevent it.

MEDIA_URL

Default: '' (Empty string)

URL that handles the media served from MEDIA_ROOT, usedfor managing stored files. It must end in a slash if setto a non-empty value. You will need to configure these files to be served in both development and productionenvironments.

If you want to use {{ MEDIA_URL }} in your templates, add'django.template.context_processors.media' in the 'context_processors'option of TEMPLATES.

Example: "http://media.example.com/&#34;

Warning

There are security risks if you are accepting uploaded content fromuntrusted users! See the security guide’s topic onUser-uploaded content for mitigation details.

Warning

MEDIA_URL and STATIC_URL must have differentvalues. See MEDIA_ROOT for more details.

MIDDLEWARE

Default: None

A list of middleware to use. See Middleware.

MIGRATION_MODULES

Default: {} (Empty dictionary)

A dictionary specifying the package where migration modules can be found on aper-app basis. The default value of this setting is an empty dictionary, butthe default package name for migration modules is migrations.

Example:

  1. {'blog': 'blog.db_migrations'}

In this case, migrations pertaining to the blog app will be contained inthe blog.db_migrations package.

If you provide the app_label argument, makemigrations willautomatically create the package if it doesn’t already exist.

When you supply None as a value for an app, Django will consider the app asan app without migrations regardless of an existing migrations submodule.This can be used, for example, in a test settings file to skip migrations whiletesting (tables will still be created for the apps’ models). If this is used inyour general project settings, remember to use the migrate—run-syncdb option if you want to create tables for the app.

MONTH_DAY_FORMAT

Default: 'F j'

The default formatting to use for date fields on Django admin change-listpages – and, possibly, by other parts of the system – in cases when only themonth and day are displayed.

For example, when a Django admin change-list page is being filtered by a datedrilldown, the header for a given day displays the day and month. Differentlocales have different formats. For example, U.S. English would say“January 1,” whereas Spanish might say “1 Enero.”

Note that if USE_L10N is set to True, then the correspondinglocale-dictated format has higher precedence and will be applied.

See allowed date format strings. See alsoDATE_FORMAT, DATETIME_FORMAT,TIME_FORMAT and YEAR_MONTH_FORMAT.

NUMBER_GROUPING

Default: 0

Number of digits grouped together on the integer part of a number.

Common use is to display a thousand separator. If this setting is 0, thenno grouping will be applied to the number. If this setting is greater than0, then THOUSAND_SEPARATOR will be used as the separator betweenthose groups.

Some locales use non-uniform digit grouping, e.g. 10,00,00,000 inen_IN. For this case, you can provide a sequence with the number of digitgroup sizes to be applied. The first number defines the size of the grouppreceding the decimal delimiter, and each number that follows defines the sizeof preceding groups. If the sequence is terminated with -1, no furthergrouping is performed. If the sequence terminates with a 0, the last groupsize is used for the remainder of the number.

Example tuple for en_IN:

  1. NUMBER_GROUPING = (3, 2, 0)

Note that if USE_L10N is set to True, then the locale-dictatedformat has higher precedence and will be applied instead.

See also DECIMAL_SEPARATOR, THOUSAND_SEPARATOR andUSE_THOUSAND_SEPARATOR.

PREPEND_WWW

Default: False

Whether to prepend the “www.” subdomain to URLs that don’t have it. This is onlyused if CommonMiddleware is installed(see Middleware). See also APPEND_SLASH.

ROOT_URLCONF

Default: Not defined

A string representing the full Python import path to your root URLconf, forexample "mydjangoapps.urls". Can be overridden on a per-request basis bysetting the attribute urlconf on the incoming HttpRequestobject. See How Django processes a request for details.

SECRET_KEY

Default: '' (Empty string)

A secret key for a particular Django installation. This is used to providecryptographic signing, and should be set to a unique,unpredictable value.

django-admin startproject automatically adds arandomly-generated SECRET_KEY to each new project.

Uses of the key shouldn’t assume that it’s text or bytes. Every use should gothrough force_str() orforce_bytes() to convert it to the desired type.

Django will refuse to start if SECRET_KEY is not set.

Warning

Keep this value secret.

Running Django with a known SECRET_KEY defeats many of Django’ssecurity protections, and can lead to privilege escalation and remote codeexecution vulnerabilities.

The secret key is used for:

Note

The default settings.py file created by django-adminstartproject creates a unique SECRET_KEY forconvenience.

SECURE_BROWSER_XSS_FILTER

Default: False

If True, the SecurityMiddleware setsthe X-XSS-Protection: 1; mode=block header on all responses that do not already have it.

Modern browsers don’t honor X-XSS-Protection HTTP header anymore. Althoughthe setting offers little practical benefit, you may still want to set theheader if you support older browsers.

SECURE_CONTENT_TYPE_NOSNIFF

Default: True

If True, the SecurityMiddlewaresets the X-Content-Type-Options: nosniff header on all responses that do notalready have it.

Changed in Django 3.0:In older versions, the default value is False.

SECURE_HSTS_INCLUDE_SUBDOMAINS

Default: False

If True, the SecurityMiddleware addsthe includeSubDomains directive to the HTTP Strict Transport Securityheader. It has no effect unless SECURE_HSTS_SECONDS is set to anon-zero value.

Warning

Setting this incorrectly can irreversibly (for the value ofSECURE_HSTS_SECONDS) break your site. Read theHTTP Strict Transport Security documentation first.

SECURE_HSTS_PRELOAD

Default: False

If True, the SecurityMiddleware addsthe preload directive to the HTTP Strict Transport Securityheader. It has no effect unless SECURE_HSTS_SECONDS is set to anon-zero value.

SECURE_HSTS_SECONDS

Default: 0

If set to a non-zero integer value, theSecurityMiddleware sets theHTTP Strict Transport Security header on all responses that do notalready have it.

Warning

Setting this incorrectly can irreversibly (for some time) break your site.Read the HTTP Strict Transport Security documentation first.

SECURE_PROXY_SSL_HEADER

Default: None

A tuple representing a HTTP header/value combination that signifies a requestis secure. This controls the behavior of the request object’s is_secure()method.

By default, is_secure() determines if a request is secure by confirmingthat a requested URL uses https://. This method is important for Django’sCSRF protection, and it may be used by your own code or third-party apps.

If your Django app is behind a proxy, though, the proxy may be “swallowing”whether the original request uses HTTPS or not. If there is a non-HTTPSconnection between the proxy and Django then is_secure() would alwaysreturn False – even for requests that were made via HTTPS by the end user.In contrast, if there is an HTTPS connection between the proxy and Django thenis_secure() would always return True – even for requests that weremade originally via HTTP.

In this situation, configure your proxy to set a custom HTTP header that tellsDjango whether the request came in via HTTPS, and setSECURE_PROXY_SSL_HEADER so that Django knows what header to look for.

Set a tuple with two elements – the name of the header to look for and therequired value. For example:

  1. SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')

This tells Django to trust the X-Forwarded-Proto header that comes from ourproxy, and any time its value is 'https', then the request is guaranteed tobe secure (i.e., it originally came in via HTTPS).

You should only set this setting if you control your proxy or have some otherguarantee that it sets/strips this header appropriately.

Note that the header needs to be in the format as used by request.META –all caps and likely starting with HTTP. (Remember, Django automaticallyadds 'HTTP' to the start of x-header names before making the headeravailable in request.META.)

Warning

Modifying this setting can compromise your site’s security. Ensure youfully understand your setup before changing it.

Make sure ALL of the following are true before setting this (assuming thevalues from the example above):

  • Your Django app is behind a proxy.
  • Your proxy strips the X-Forwarded-Proto header from all incomingrequests. In other words, if end users include that header in theirrequests, the proxy will discard it.
  • Your proxy sets the X-Forwarded-Proto header and sends it to Django,but only for requests that originally come in via HTTPS.If any of those are not true, you should keep this setting set to Noneand find another way of determining HTTPS, perhaps via custom middleware.

SECURE_REDIRECT_EXEMPT

Default: [] (Empty list)

If a URL path matches a regular expression in this list, the request will not beredirected to HTTPS. If SECURE_SSL_REDIRECT is False, thissetting has no effect.

SECURE_REFERRER_POLICY

New in Django 3.0:

Default: None

If configured, the SecurityMiddleware setsthe Referrer Policy header on all responses that do not already have itto the value provided.

SECURE_SSL_HOST

Default: None

If a string (e.g. secure.example.com), all SSL redirects will be directedto this host rather than the originally-requested host(e.g. www.example.com). If SECURE_SSL_REDIRECT is False, thissetting has no effect.

SECURE_SSL_REDIRECT

Default: False

If True, the SecurityMiddlewareredirects all non-HTTPS requests to HTTPS (except forthose URLs matching a regular expression listed inSECURE_REDIRECT_EXEMPT).

Note

If turning this to True causes infinite redirects, it probably meansyour site is running behind a proxy and can’t tell which requests are secureand which are not. Your proxy likely sets a header to indicate securerequests; you can correct the problem by finding out what that header is andconfiguring the SECURE_PROXY_SSL_HEADER setting accordingly.

SERIALIZATION_MODULES

Default: Not defined

A dictionary of modules containing serializer definitions (provided asstrings), keyed by a string identifier for that serialization type. Forexample, to define a YAML serializer, use:

  1. SERIALIZATION_MODULES = {'yaml': 'path.to.yaml_serializer'}

SERVER_EMAIL

Default: 'root@localhost'

The email address that error messages come from, such as those sent toADMINS and MANAGERS.

Why are my emails sent from a different address?

This address is used only for error messages. It is not the address thatregular email messages sent with send_mail()come from; for that, see DEFAULT_FROM_EMAIL.

SHORT_DATE_FORMAT

Default: 'm/d/Y' (e.g. 12/31/2003)

An available formatting that can be used for displaying date fields ontemplates. Note that if USE_L10N is set to True, then thecorresponding locale-dictated format has higher precedence and will be applied.See allowed date format strings.

See also DATE_FORMAT and SHORT_DATETIME_FORMAT.

SHORT_DATETIME_FORMAT

Default: 'm/d/Y P' (e.g. 12/31/2003 4 p.m.)

An available formatting that can be used for displaying datetime fields ontemplates. Note that if USE_L10N is set to True, then thecorresponding locale-dictated format has higher precedence and will be applied.See allowed date format strings.

See also DATE_FORMAT and SHORT_DATE_FORMAT.

SIGNING_BACKEND

Default: 'django.core.signing.TimestampSigner'

The backend used for signing cookies and other data.

See also the Cryptographic signing documentation.

SILENCED_SYSTEM_CHECKS

Default: [] (Empty list)

A list of identifiers of messages generated by the system check framework(i.e. ["models.W001"]) that you wish to permanently acknowledge and ignore.Silenced checks will not be output to the console.

See also the System check framework documentation.

TEMPLATES

Default: [] (Empty list)

A list containing the settings for all template engines to be used withDjango. Each item of the list is a dictionary containing the options for anindividual engine.

Here’s a setup that tells the Django template engine to load templates from thetemplates subdirectory inside each installed application:

  1. TEMPLATES = [
  2. {
  3. 'BACKEND': 'django.template.backends.django.DjangoTemplates',
  4. 'APP_DIRS': True,
  5. },
  6. ]

The following options are available for all backends.

BACKEND

Default: Not defined

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

  • 'django.template.backends.django.DjangoTemplates'
  • 'django.template.backends.jinja2.Jinja2'You can use a template backend that doesn’t ship with Django by settingBACKEND to a fully-qualified path (i.e. 'mypackage.whatever.Backend').

NAME

Default: see below

The alias for this particular template engine. It’s an identifier that allowsselecting an engine for rendering. Aliases must be unique across allconfigured template engines.

It defaults to the name of the module defining the engine class, i.e. thenext to last piece of BACKEND, when it isn’tprovided. For example if the backend is 'mypackage.whatever.Backend' thenits default name is 'whatever'.

DIRS

Default: [] (Empty list)

Directories where the engine should look for template source files, in searchorder.

APP_DIRS

Default: False

Whether the engine should look for template source files inside installedapplications.

Note

The default settings.py file created by django-adminstartproject sets 'APP_DIRS': True.

OPTIONS

Default: {} (Empty dict)

Extra parameters to pass to the template backend. Available parameters varydepending on the template backend. SeeDjangoTemplates andJinja2 for the options of thebuilt-in backends.

TEST_RUNNER

Default: 'django.test.runner.DiscoverRunner'

The name of the class to use for starting the test suite. SeeUsing different testing frameworks.

TEST_NON_SERIALIZED_APPS

Default: [] (Empty list)

In order to restore the database state between tests forTransactionTestCases and database backends without transactions, Djangowill serialize the contents of all appswhen it starts the test run so it can then reload from that copy before runningtests that need it.

This slows down the startup time of the test runner; if you have apps thatyou know don’t need this feature, you can add their full names in here (e.g.'django.contrib.contenttypes') to exclude them from this serializationprocess.

THOUSAND_SEPARATOR

Default: ',' (Comma)

Default thousand separator used when formatting numbers. This setting isused only when USE_THOUSAND_SEPARATOR is True andNUMBER_GROUPING is greater than 0.

Note that if USE_L10N is set to True, then the locale-dictatedformat has higher precedence and will be applied instead.

See also NUMBER_GROUPING, DECIMAL_SEPARATOR andUSE_THOUSAND_SEPARATOR.

TIME_FORMAT

Default: 'P' (e.g. 4 p.m.)

The default formatting to use for displaying time fields in any part of thesystem. Note that if USE_L10N is set to True, then thelocale-dictated format has higher precedence and will be applied instead. Seeallowed date format strings.

See also DATE_FORMAT and DATETIME_FORMAT.

TIME_INPUT_FORMATS

Default:

  1. [
  2. '%H:%M:%S', # '14:30:59'
  3. '%H:%M:%S.%f', # '14:30:59.000200'
  4. '%H:%M', # '14:30'
  5. ]

A list of formats that will be accepted when inputting data on a time field.Formats will be tried in order, using the first valid one. Note that theseformat strings use Python’s datetime module syntax, not the format strings from the datetemplate filter.

When USE_L10N is True, the locale-dictated format has higherprecedence and will be applied instead.

See also DATE_INPUT_FORMATS and DATETIME_INPUT_FORMATS.

TIME_ZONE

Default: 'America/Chicago'

A string representing the time zone for this installation. See the list oftime zones.

Note

Since Django was first released with the TIME_ZONE set to'America/Chicago', the global setting (used if nothing is defined inyour project’s settings.py) remains 'America/Chicago' for backwardscompatibility. New project templates default to 'UTC'.

Note that this isn’t necessarily the time zone of the server. For example, oneserver may serve multiple Django-powered sites, each with a separate time zonesetting.

When USE_TZ is False, this is the time zone in which Djangowill store all datetimes. When USE_TZ is True, this is thedefault time zone that Django will use to display datetimes in templates andto interpret datetimes entered in forms.

On Unix environments (where time.tzset() is implemented), Django sets theos.environ['TZ'] variable to the time zone you specify in theTIME_ZONE setting. Thus, all your views and models willautomatically operate in this time zone. However, Django won’t set the TZenvironment variable if you’re using the manual configuration option asdescribed in manually configuring settings. If Django doesn’t set the TZenvironment variable, it’s up to you to ensure your processes are running inthe correct environment.

Note

Django cannot reliably use alternate time zones in a Windows environment.If you’re running Django on Windows, TIME_ZONE must be set tomatch the system time zone.

USE_I18N

Default: True

A boolean that specifies whether Django’s translation system should be enabled.This provides a way to turn it off, for performance. If this is set toFalse, Django will make some optimizations so as not to load thetranslation machinery.

See also LANGUAGE_CODE, USE_L10N and USE_TZ.

Note

The default settings.py file created by django-adminstartproject includes USE_I18N = True for convenience.

USE_L10N

Default: False

A boolean that specifies if localized formatting of data will be enabled bydefault or not. If this is set to True, e.g. Django will display numbers anddates using the format of the current locale.

See also LANGUAGE_CODE, USE_I18N and USE_TZ.

Note

The default settings.py file created by django-adminstartproject includes USE_L10N = True for convenience.

USE_THOUSAND_SEPARATOR

Default: False

A boolean that specifies whether to display numbers using a thousand separator.When USE_L10N is set to True and if this is also set toTrue, Django will use the values of THOUSAND_SEPARATOR andNUMBER_GROUPING to format numbers unless the locale already has anexisting thousands separator. If there is a thousands separator in the localeformat, it will have higher precedence and will be applied instead.

See also DECIMAL_SEPARATOR, NUMBER_GROUPING andTHOUSAND_SEPARATOR.

USE_TZ

Default: False

A boolean that specifies if datetimes will be timezone-aware by default or not.If this is set to True, Django will use timezone-aware datetimes internally.Otherwise, Django will use naive datetimes in local time.

See also TIME_ZONE, USE_I18N and USE_L10N.

Note

The default settings.py file created bydjango-admin startproject includesUSE_TZ = True for convenience.

USE_X_FORWARDED_HOST

Default: False

A boolean that specifies whether to use the X-Forwarded-Host header inpreference to the Host header. This should only be enabled if a proxywhich sets this header is in use.

This setting takes priority over USE_X_FORWARDED_PORT. PerRFC 7239#page-7, the X-Forwarded-Host header can include the portnumber, in which case you shouldn’t use USE_X_FORWARDED_PORT.

USE_X_FORWARDED_PORT

Default: False

A boolean that specifies whether to use the X-Forwarded-Port header inpreference to the SERVER_PORT META variable. This should only beenabled if a proxy which sets this header is in use.

USE_X_FORWARDED_HOST takes priority over this setting.

WSGI_APPLICATION

Default: None

The full Python path of the WSGI application object that Django’s built-inservers (e.g. runserver) will use. The django-adminstartproject management command will create a standardwsgi.py file with an application callable in it, and point this settingto that application.

If not set, the return value of django.core.wsgi.get_wsgi_application()will be used. In this case, the behavior of runserver will beidentical to previous Django versions.

YEAR_MONTH_FORMAT

Default: 'F Y'

The default formatting to use for date fields on Django admin change-listpages – and, possibly, by other parts of the system – in cases when only theyear and month are displayed.

For example, when a Django admin change-list page is being filtered by a datedrilldown, the header for a given month displays the month and the year.Different locales have different formats. For example, U.S. English would say“January 2006,” whereas another locale might say “2006/January.”

Note that if USE_L10N is set to True, then the correspondinglocale-dictated format has higher precedence and will be applied.

See allowed date format strings. See alsoDATE_FORMAT, DATETIME_FORMAT, TIME_FORMATand MONTH_DAY_FORMAT.

X_FRAME_OPTIONS

Default: 'DENY'

The default value for the X-Frame-Options header used byXFrameOptionsMiddleware. See theclickjacking protection documentation.

Changed in Django 3.0:In older versions, the default value is SAMEORIGIN.

Auth

Settings for django.contrib.auth.

AUTHENTICATION_BACKENDS

Default: ['django.contrib.auth.backends.ModelBackend']

A list of authentication backend classes (as strings) to use when attempting toauthenticate a user. See the authentication backends documentation for details.

AUTH_USER_MODEL

Default: 'auth.User'

The model to use to represent a User. See Substituting a custom User model.

Warning

You cannot change the AUTH_USER_MODEL setting during the lifetime ofa project (i.e. once you have made and migrated models that depend on it)without serious effort. It is intended to be set at the project start,and the model it refers to must be available in the first migration ofthe app that it lives in.See Substituting a custom User model for more details.

LOGIN_REDIRECT_URL

Default: '/accounts/profile/'

The URL or named URL pattern where requests areredirected after login when the LoginViewdoesn’t get a next GET parameter.

LOGIN_URL

Default: '/accounts/login/'

The URL or named URL pattern where requests areredirected for login when using thelogin_required() decorator,LoginRequiredMixin, orAccessMixin.

LOGOUT_REDIRECT_URL

Default: None

The URL or named URL pattern where requests areredirected after logout if LogoutViewdoesn’t have a next_page attribute.

If None, no redirect will be performed and the logout view will berendered.

PASSWORD_RESET_TIMEOUT_DAYS

Default: 3

The minimum number of days a password reset link is valid for. Depending onwhen the link is generated, it will be valid for up to a day longer.

Used by the PasswordResetConfirmView.

PASSWORD_HASHERS

See How Django stores passwords.

Default:

  1. [
  2. 'django.contrib.auth.hashers.PBKDF2PasswordHasher',
  3. 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
  4. 'django.contrib.auth.hashers.Argon2PasswordHasher',
  5. 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
  6. ]

AUTH_PASSWORD_VALIDATORS

Default: [] (Empty list)

The list of validators that are used to check the strength of user’s passwords.See Password validation for more details. By default, no validation isperformed and all passwords are accepted.

Messages

Settings for django.contrib.messages.

MESSAGE_LEVEL

Default: messages.INFO

Sets the minimum message level that will be recorded by the messagesframework. See message levels for more details.

Important

If you override MESSAGE_LEVEL in your settings file and rely on any ofthe built-in constants, you must import the constants module directly toavoid the potential for circular imports, e.g.:

  1. from django.contrib.messages import constants as message_constants
  2. MESSAGE_LEVEL = message_constants.DEBUG

If desired, you may specify the numeric values for the constants directlyaccording to the values in the above constants table.

MESSAGE_STORAGE

Default: 'django.contrib.messages.storage.fallback.FallbackStorage'

Controls where Django stores message data. Valid values are:

  • 'django.contrib.messages.storage.fallback.FallbackStorage'
  • 'django.contrib.messages.storage.session.SessionStorage'
  • 'django.contrib.messages.storage.cookie.CookieStorage'See message storage backends for more details.

The backends that use cookies –CookieStorage andFallbackStorage –use the value of SESSION_COOKIE_DOMAIN, SESSION_COOKIE_SECUREand SESSION_COOKIE_HTTPONLY when setting their cookies.

MESSAGE_TAGS

Default:

  1. {
  2. messages.DEBUG: 'debug',
  3. messages.INFO: 'info',
  4. messages.SUCCESS: 'success',
  5. messages.WARNING: 'warning',
  6. messages.ERROR: 'error',
  7. }

This sets the mapping of message level to message tag, which is typicallyrendered as a CSS class in HTML. If you specify a value, it will extendthe default. This means you only have to specify those values which you needto override. See Displaying messages above for more details.

Important

If you override MESSAGE_TAGS in your settings file and rely on any ofthe built-in constants, you must import the constants module directly toavoid the potential for circular imports, e.g.:

  1. from django.contrib.messages import constants as message_constants
  2. MESSAGE_TAGS = {message_constants.INFO: ''}

If desired, you may specify the numeric values for the constants directlyaccording to the values in the above constants table.

Sessions

Settings for django.contrib.sessions.

SESSION_CACHE_ALIAS

Default: 'default'

If you’re using cache-based session storage,this selects the cache to use.

Default: 1209600 (2 weeks, in seconds)

The age of session cookies, in seconds.

Default: None

The domain to use for session cookies. Set this to a string such as"example.com" for cross-domain cookies, or use None for a standarddomain cookie.

Be cautious when updating this setting on a production site. If you updatethis setting to enable cross-domain cookies on a site that previously usedstandard domain cookies, existing user cookies will be set to the olddomain. This may result in them being unable to log in as long as these cookiespersist.

This setting also affects cookies set by django.contrib.messages.

Default: True

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

HttpOnly is a flag included in a Set-Cookie HTTP response header. It’s part ofthe RFC 6265 standard for cookies and can be a useful way to mitigate therisk of a client-side script accessing the protected cookie data.

This makes it less trivial for an attacker to escalate a cross-site scriptingvulnerability into full hijacking of a user’s session. There aren’t many goodreasons for turning this off. Your code shouldn’t read session cookies fromJavaScript.

Default: 'sessionid'

The name of the cookie to use for sessions. This can be whatever you want(as long as it’s different from the other cookie names in your application).

Default: '/'

The path set on the session cookie. This should either match the URL path of yourDjango installation or be 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 session cookie.

Default: 'Lax'

The value of the SameSite flag on the session cookie. This flag prevents thecookie from being sent in cross-site requests thus preventing CSRF attacks andmaking some methods of stealing session cookie impossible.

Possible values for the setting are:

  • 'Strict': prevents the cookie from being sent by the browser to thetarget site in all cross-site browsing context, even when following a regularlink.

For example, for a GitHub-like website this would mean that if a logged-inuser follows a link to a private GitHub project posted on a corporatediscussion forum or email, GitHub will not receive the session cookie and theuser won’t be able to access the project. A bank website, however, mostlikely doesn’t want to allow any transactional pages to be linked fromexternal sites so the 'Strict' flag would be appropriate.

  • 'Lax' (default): provides a balance between security and usability forwebsites that want to maintain user’s logged-in session after the userarrives from an external link.

In the GitHub scenario, the session cookie would be allowed when following aregular link from an external website and be blocked in CSRF-prone requestmethods (e.g. POST).

  • None: disables the flag.

Default: False

Whether to use a secure cookie for the session cookie. If this is set toTrue, the cookie will be marked as “secure”, which means browsers mayensure that the cookie is only sent under an HTTPS connection.

Leaving this setting off isn’t a good idea because an attacker could capture anunencrypted session cookie with a packet sniffer and use the cookie to hijackthe user’s session.

SESSION_ENGINE

Default: 'django.contrib.sessions.backends.db'

Controls where Django stores session data. Included engines are:

  • 'django.contrib.sessions.backends.db'
  • 'django.contrib.sessions.backends.file'
  • 'django.contrib.sessions.backends.cache'
  • 'django.contrib.sessions.backends.cached_db'
  • 'django.contrib.sessions.backends.signed_cookies'See Configuring the session engine for more details.

SESSION_EXPIRE_AT_BROWSER_CLOSE

Default: False

Whether to expire the session when the user closes their browser. SeeBrowser-length sessions vs. persistent sessions.

SESSION_FILE_PATH

Default: None

If you’re using file-based session storage, this sets the directory inwhich Django will store session data. When the default value (None) isused, Django will use the standard temporary directory for the system.

SESSION_SAVE_EVERY_REQUEST

Default: False

Whether to save the session data on every request. If this is False(default), then the session data will only be saved if it has been modified –that is, if any of its dictionary values have been assigned or deleted. Emptysessions won’t be created, even if this setting is active.

SESSION_SERIALIZER

Default: 'django.contrib.sessions.serializers.JSONSerializer'

Full import path of a serializer class to use for serializing session data.Included serializers are:

  • 'django.contrib.sessions.serializers.PickleSerializer'
  • 'django.contrib.sessions.serializers.JSONSerializer'See Session serialization for details, including a warning regardingpossible remote code execution when usingPickleSerializer.

Sites

Settings for django.contrib.sites.

SITE_ID

Default: Not defined

The ID, as an integer, of the current site in the django_site databasetable. This is used so that application data can hook into specific sitesand a single database can manage content for multiple sites.

Static Files

Settings for django.contrib.staticfiles.

STATIC_ROOT

Default: None

The absolute path to the directory where collectstatic will collectstatic files for deployment.

Example: "/var/www/example.com/static/"

If the staticfiles contrib app is enabled(as in the default project template), the collectstatic managementcommand will collect static files into this directory. See the how-to onmanaging static files for more details aboutusage.

Warning

This should be an initially empty destination directory for collectingyour static files from their permanent locations into one directory forease of deployment; it is not a place to store your static filespermanently. You should do that in directories that will be found bystaticfiles’sfinders, which by default, are'static/' app sub-directories and any directories you include inSTATICFILES_DIRS).

STATIC_URL

Default: None

URL to use when referring to static files located in STATIC_ROOT.

Example: "/static/" or "http://static.example.com/&#34;

If not None, this will be used as the base path forasset definitions (the Media class) and thestaticfiles app.

It must end in a slash if set to a non-empty value.

You may need to configure these files to be served in development and will definitely need to do soin production.

STATICFILES_DIRS

Default: [] (Empty list)

This setting defines the additional locations the staticfiles app will traverseif the FileSystemFinder finder is enabled, e.g. if you use thecollectstatic or findstatic management command or use thestatic file serving view.

This should be set to a list of strings that contain full paths toyour additional files directory(ies) e.g.:

  1. STATICFILES_DIRS = [
  2. "/home/special.polls.com/polls/static",
  3. "/home/polls.com/polls/static",
  4. "/opt/webfiles/common",
  5. ]

Note that these paths should use Unix-style forward slashes, even on Windows(e.g. "C:/Users/user/mysite/extra_static_content").

Prefixes (optional)

In case you want to refer to files in one of the locations with an additionalnamespace, you can optionally provide a prefix as (prefix, path)tuples, e.g.:

  1. STATICFILES_DIRS = [
  2. # ...
  3. ("downloads", "/opt/webfiles/stats"),
  4. ]

For example, assuming you have STATIC_URL set to '/static/', thecollectstatic management command would collect the “stats” filesin a 'downloads' subdirectory of STATIC_ROOT.

This would allow you to refer to the local file'/opt/webfiles/stats/polls_20101022.tar.gz' with'/static/downloads/polls_20101022.tar.gz' in your templates, e.g.:

  1. <a href="{% static "downloads/polls_20101022.tar.gz" %}">

STATICFILES_STORAGE

Default: 'django.contrib.staticfiles.storage.StaticFilesStorage'

The file storage engine to use when collecting static files with thecollectstatic management command.

A ready-to-use instance of the storage backend defined in this settingcan be found at django.contrib.staticfiles.storage.staticfiles_storage.

For an example, see Serving static files from a cloud service or CDN.

STATICFILES_FINDERS

Default:

  1. [
  2. 'django.contrib.staticfiles.finders.FileSystemFinder',
  3. 'django.contrib.staticfiles.finders.AppDirectoriesFinder',
  4. ]

The list of finder backends that know how to find static files invarious locations.

The default will find files stored in the STATICFILES_DIRS setting(using django.contrib.staticfiles.finders.FileSystemFinder) and in astatic subdirectory of each app (usingdjango.contrib.staticfiles.finders.AppDirectoriesFinder). If multiplefiles with the same name are present, the first file that is found will beused.

One finder is disabled by default:django.contrib.staticfiles.finders.DefaultStorageFinder. If added toyour STATICFILES_FINDERS setting, it will look for static files inthe default file storage as defined by the DEFAULT_FILE_STORAGEsetting.

Note

When using the AppDirectoriesFinder finder, make sure your appscan be found by staticfiles by adding the app to theINSTALLED_APPS setting of your site.

Static file finders are currently considered a private interface, and thisinterface is thus undocumented.

Core Settings Topical Index

Cache

Database

Debugging

Email

Error reporting

File uploads

Forms

Globalization (i18n/l10n)

HTTP

Logging

Models

Security

Serialization

Templates

Testing

URLs