mirror of https://github.com/django/django.git
3446 lines
103 KiB
Plaintext
3446 lines
103 KiB
Plaintext
========
|
||
Settings
|
||
========
|
||
|
||
.. contents::
|
||
:local:
|
||
:depth: 1
|
||
|
||
.. warning::
|
||
|
||
Be careful when you override settings, especially when the default value
|
||
is a non-empty list or dictionary, such as :setting:`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 :doc:`settings topic
|
||
guide </topics/settings>`.
|
||
|
||
.. setting:: ABSOLUTE_URL_OVERRIDES
|
||
|
||
``ABSOLUTE_URL_OVERRIDES``
|
||
--------------------------
|
||
|
||
Default: ``{}`` (Empty dictionary)
|
||
|
||
A dictionary mapping ``"app_label.model_name"`` strings to functions that take
|
||
a model object and return its URL. This is a way of inserting or overriding
|
||
``get_absolute_url()`` methods on a per-installation basis. Example::
|
||
|
||
ABSOLUTE_URL_OVERRIDES = {
|
||
'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,
|
||
'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
|
||
}
|
||
|
||
Note that the model name used in this setting should be all lower-case, regardless
|
||
of the case of the actual model class name.
|
||
|
||
.. setting:: ADMINS
|
||
|
||
``ADMINS``
|
||
----------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
A list of all the people who get code error notifications. When
|
||
``DEBUG=False`` and a view raises an exception, Django will email these people
|
||
with the full exception information. Each item in the list should be a tuple
|
||
of (Full name, email address). Example::
|
||
|
||
[('John', 'john@example.com'), ('Mary', 'mary@example.com')]
|
||
|
||
Note that Django will email *all* of these people whenever an error happens.
|
||
See :doc:`/howto/error-reporting` for more information.
|
||
|
||
.. setting:: ALLOWED_HOSTS
|
||
|
||
``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 :ref:`HTTP Host header attacks
|
||
<host-headers-virtual-hosting>`, 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
|
||
:setting:`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.
|
||
|
||
.. _`fully qualified domain name (FQDN)`: https://en.wikipedia.org/wiki/Fully_qualified_domain_name
|
||
|
||
If the ``Host`` header (or ``X-Forwarded-Host`` if
|
||
:setting:`USE_X_FORWARDED_HOST` is enabled) does not match any value in this
|
||
list, the :meth:`django.http.HttpRequest.get_host()` method will raise
|
||
:exc:`~django.core.exceptions.SuspiciousOperation`.
|
||
|
||
When :setting:`DEBUG` is ``True`` and ``ALLOWED_HOSTS`` is empty, the host
|
||
is validated against ``['localhost', '127.0.0.1', '[::1]']``.
|
||
|
||
``ALLOWED_HOSTS`` is also :ref:`checked when running tests
|
||
<topics-testing-advanced-multiple-hosts>`.
|
||
|
||
This validation only applies via :meth:`~django.http.HttpRequest.get_host()`;
|
||
if your code accesses the ``Host`` header directly from ``request.META`` you
|
||
are bypassing this security protection.
|
||
|
||
.. setting:: APPEND_SLASH
|
||
|
||
``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 :setting:`APPEND_SLASH` setting is only used if
|
||
:class:`~django.middleware.common.CommonMiddleware` is installed
|
||
(see :doc:`/topics/http/middleware`). See also :setting:`PREPEND_WWW`.
|
||
|
||
.. setting:: CACHES
|
||
|
||
``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 :setting:`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.
|
||
|
||
.. setting:: CACHES-BACKEND
|
||
|
||
``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
|
||
:setting:`BACKEND <CACHES-BACKEND>` to a fully-qualified path of a cache
|
||
backend class (i.e. ``mypackage.backends.whatever.WhateverCache``).
|
||
|
||
.. setting:: CACHES-KEY_FUNCTION
|
||
|
||
``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 :ref:`cache documentation <cache_key_transformation>` for more
|
||
information.
|
||
|
||
.. setting:: CACHES-KEY_PREFIX
|
||
|
||
``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 :ref:`cache documentation <cache_key_prefixing>` for more information.
|
||
|
||
.. setting:: CACHES-LOCATION
|
||
|
||
``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',
|
||
}
|
||
}
|
||
|
||
.. setting:: CACHES-OPTIONS
|
||
|
||
``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
|
||
:ref:`cache arguments <cache_arguments>` documentation. For more information,
|
||
consult your backend module's own documentation.
|
||
|
||
.. setting:: CACHES-TIMEOUT
|
||
|
||
``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.
|
||
|
||
.. setting:: CACHES-VERSION
|
||
|
||
``VERSION``
|
||
~~~~~~~~~~~
|
||
|
||
Default: ``1``
|
||
|
||
The default version number for cache keys generated by the Django server.
|
||
|
||
See the :ref:`cache documentation <cache_versioning>` for more information.
|
||
|
||
.. setting:: CACHE_MIDDLEWARE_ALIAS
|
||
|
||
``CACHE_MIDDLEWARE_ALIAS``
|
||
--------------------------
|
||
|
||
Default: ``default``
|
||
|
||
The cache connection to use for the :ref:`cache middleware
|
||
<the-per-site-cache>`.
|
||
|
||
.. setting:: CACHE_MIDDLEWARE_KEY_PREFIX
|
||
|
||
``CACHE_MIDDLEWARE_KEY_PREFIX``
|
||
-------------------------------
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
A string which will be prefixed to the cache keys generated by the :ref:`cache
|
||
middleware <the-per-site-cache>`. This prefix is combined with the
|
||
:setting:`KEY_PREFIX <CACHES-KEY_PREFIX>` setting; it does not replace it.
|
||
|
||
See :doc:`/topics/cache`.
|
||
|
||
.. setting:: CACHE_MIDDLEWARE_SECONDS
|
||
|
||
``CACHE_MIDDLEWARE_SECONDS``
|
||
----------------------------
|
||
|
||
Default: ``600``
|
||
|
||
The default number of seconds to cache a page for the :ref:`cache middleware
|
||
<the-per-site-cache>`.
|
||
|
||
See :doc:`/topics/cache`.
|
||
|
||
.. _settings-csrf:
|
||
|
||
.. setting:: CSRF_COOKIE_AGE
|
||
|
||
``CSRF_COOKIE_AGE``
|
||
-------------------
|
||
|
||
Default: ``31449600`` (approximately 1 year, in seconds)
|
||
|
||
The age of CSRF cookies, in seconds.
|
||
|
||
The reason for setting a long-lived expiration time is to avoid problems in
|
||
the case of a user closing a browser or bookmarking a page and then loading
|
||
that page from a browser cache. Without persistent cookies, the form submission
|
||
would fail in this case.
|
||
|
||
Some browsers (specifically Internet Explorer) can disallow the use of
|
||
persistent cookies or can have the indexes to the cookie jar corrupted on disk,
|
||
thereby causing CSRF protection checks to (sometimes intermittently) fail.
|
||
Change this setting to ``None`` to use session-based CSRF cookies, which
|
||
keep the cookies in-memory instead of on persistent storage.
|
||
|
||
.. setting:: CSRF_COOKIE_DOMAIN
|
||
|
||
``CSRF_COOKIE_DOMAIN``
|
||
----------------------
|
||
|
||
Default: ``None``
|
||
|
||
The domain to be used when setting the CSRF cookie. This can be useful for
|
||
easily allowing cross-subdomain requests to be excluded from the normal cross
|
||
site request forgery protection. It should be set to a string such as
|
||
``".example.com"`` to allow a POST request from a form on one subdomain to be
|
||
accepted by a view served from another subdomain.
|
||
|
||
Please note that the presence of this setting does not imply that Django's CSRF
|
||
protection is safe from cross-subdomain attacks by default - please see the
|
||
:ref:`CSRF limitations <csrf-limitations>` section.
|
||
|
||
.. setting:: CSRF_COOKIE_HTTPONLY
|
||
|
||
``CSRF_COOKIE_HTTPONLY``
|
||
------------------------
|
||
|
||
Default: ``False``
|
||
|
||
Whether to use ``HttpOnly`` flag on the CSRF cookie. If this is set to
|
||
``True``, client-side JavaScript will not to be able to access the CSRF cookie.
|
||
|
||
Designating the CSRF cookie as ``HttpOnly`` doesn't offer any practical
|
||
protection because CSRF is only to protect against cross-domain attacks. If an
|
||
attacker can read the cookie via JavaScript, they're already on the same domain
|
||
as far as the browser knows, so they can do anything they like anyway. (XSS is
|
||
a much bigger hole than CSRF.)
|
||
|
||
Although the setting offers little practical benefit, it's sometimes required
|
||
by security auditors.
|
||
|
||
If you enable this and need to send the value of the CSRF token with an AJAX
|
||
request, your JavaScript must pull the value from a hidden CSRF token form
|
||
input on the page instead of from the cookie.
|
||
|
||
See :setting:`SESSION_COOKIE_HTTPONLY` for details on ``HttpOnly``.
|
||
|
||
.. setting:: CSRF_COOKIE_NAME
|
||
|
||
``CSRF_COOKIE_NAME``
|
||
--------------------
|
||
|
||
Default: ``'csrftoken'``
|
||
|
||
The name of the cookie to use for the CSRF authentication token. This can be
|
||
whatever you want (as long as it's different from the other cookie names in
|
||
your application). See :doc:`/ref/csrf`.
|
||
|
||
.. setting:: CSRF_COOKIE_PATH
|
||
|
||
``CSRF_COOKIE_PATH``
|
||
--------------------
|
||
|
||
Default: ``'/'``
|
||
|
||
The path set on the CSRF cookie. This should either match the URL path of your
|
||
Django installation or be a parent of that path.
|
||
|
||
This is useful if you have multiple Django instances running under the same
|
||
hostname. They can use different cookie paths, and each instance will only see
|
||
its own CSRF cookie.
|
||
|
||
.. setting:: CSRF_COOKIE_SECURE
|
||
|
||
``CSRF_COOKIE_SECURE``
|
||
----------------------
|
||
|
||
Default: ``False``
|
||
|
||
Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``,
|
||
the cookie will be marked as "secure," which means browsers may ensure that the
|
||
cookie is only sent with an HTTPS connection.
|
||
|
||
.. setting:: CSRF_USE_SESSIONS
|
||
|
||
``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 :mod:`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.
|
||
|
||
.. setting:: CSRF_FAILURE_VIEW
|
||
|
||
``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 :doc:`CSRF protection </ref/csrf>`. 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 :class:`~django.http.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.
|
||
|
||
.. setting:: CSRF_HEADER_NAME
|
||
|
||
``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'``.
|
||
|
||
.. setting:: CSRF_TRUSTED_ORIGINS
|
||
|
||
``CSRF_TRUSTED_ORIGINS``
|
||
------------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
A list of hosts which are trusted origins for unsafe requests (e.g. ``POST``).
|
||
For a :meth:`secure <django.http.HttpRequest.is_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``.
|
||
|
||
.. setting:: DATABASES
|
||
|
||
``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 :setting:`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 :setting:`ENGINE <DATABASE-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:
|
||
|
||
.. setting:: DATABASE-ATOMIC_REQUESTS
|
||
|
||
``ATOMIC_REQUESTS``
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
Default: ``False``
|
||
|
||
Set this to ``True`` to wrap each view in a transaction on this database. See
|
||
:ref:`tying-transactions-to-http-requests`.
|
||
|
||
.. setting:: DATABASE-AUTOCOMMIT
|
||
|
||
``AUTOCOMMIT``
|
||
~~~~~~~~~~~~~~
|
||
|
||
Default: ``True``
|
||
|
||
Set this to ``False`` if you want to :ref:`disable Django's transaction
|
||
management <deactivate-transaction-management>` and implement your own.
|
||
|
||
.. setting:: DATABASE-ENGINE
|
||
|
||
``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``).
|
||
|
||
.. setting:: HOST
|
||
|
||
``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 :setting:`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 :setting:`HOST` to 'localhost'
|
||
or '127.0.0.1' ('host' lines in ``pg_hba.conf``).
|
||
On Windows, you should always define :setting:`HOST`, as UNIX domain sockets
|
||
are not available.
|
||
|
||
.. setting:: NAME
|
||
|
||
``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``).
|
||
|
||
.. setting:: CONN_MAX_AGE
|
||
|
||
``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.
|
||
|
||
.. setting:: OPTIONS
|
||
|
||
``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
|
||
:doc:`Database Backends </ref/databases>` documentation. For more information,
|
||
consult your backend module's own documentation.
|
||
|
||
.. setting:: PASSWORD
|
||
|
||
``PASSWORD``
|
||
~~~~~~~~~~~~
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
The password to use when connecting to the database. Not used with SQLite.
|
||
|
||
.. setting:: PORT
|
||
|
||
``PORT``
|
||
~~~~~~~~
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
The port to use when connecting to the database. An empty string means the
|
||
default port. Not used with SQLite.
|
||
|
||
.. setting:: DATABASE-TIME_ZONE
|
||
|
||
``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``. The same values are
|
||
accepted as in the general :setting:`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 :setting:`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 :setting:`USE_TZ` is ``True`` and the database supports time zones (e.g.
|
||
PostgreSQL), it is an error to set this option.
|
||
|
||
When :setting:`USE_TZ` is ``False``, it is an error to set this option.
|
||
|
||
.. setting:: DATABASE-DISABLE_SERVER_SIDE_CURSORS
|
||
|
||
``DISABLE_SERVER_SIDE_CURSORS``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Default: ``False``
|
||
|
||
Set this to ``True`` if you want to disable the use of server-side cursors with
|
||
:meth:`.QuerySet.iterator`. :ref:`transaction-pooling-server-side-cursors`
|
||
describes the use case.
|
||
|
||
This is a PostgreSQL-specific setting.
|
||
|
||
.. setting:: USER
|
||
|
||
``USER``
|
||
~~~~~~~~
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
The username to use when connecting to the database. Not used with SQLite.
|
||
|
||
.. setting:: DATABASE-TEST
|
||
|
||
``TEST``
|
||
~~~~~~~~
|
||
|
||
Default: ``{}`` (Empty dictionary)
|
||
|
||
A dictionary of settings for test databases; for more details about the
|
||
creation and use of test databases, see :ref:`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:
|
||
|
||
.. setting:: TEST_CHARSET
|
||
|
||
``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.
|
||
|
||
.. _PostgreSQL: https://www.postgresql.org/docs/current/static/multibyte.html
|
||
.. _MySQL: https://dev.mysql.com/doc/refman/en/charset-database.html
|
||
|
||
.. setting:: TEST_COLLATION
|
||
|
||
``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).
|
||
|
||
.. _MySQL manual: MySQL_
|
||
|
||
.. setting:: TEST_DEPENDENCIES
|
||
|
||
``DEPENDENCIES``
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
Default: ``['default']``, for all databases other than ``default``,
|
||
which has no dependencies.
|
||
|
||
The creation-order dependencies of the database. See the documentation
|
||
on :ref:`controlling the creation order of test databases
|
||
<topics-testing-creation-dependencies>` for details.
|
||
|
||
.. setting:: TEST_MIRROR
|
||
|
||
``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
|
||
:ref:`testing primary/replica configurations
|
||
<topics-testing-primaryreplica>` for details.
|
||
|
||
.. setting:: TEST_NAME
|
||
|
||
``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 :ref:`the-test-database`.
|
||
|
||
.. setting:: TEST_SERIALIZE
|
||
|
||
``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 :ref:`serialized_rollback=True <test-case-serialized-rollback>`.
|
||
|
||
.. setting:: TEST_TEMPLATE
|
||
|
||
``TEMPLATE``
|
||
^^^^^^^^^^^^
|
||
|
||
This is a PostgreSQL-specific setting.
|
||
|
||
The name of a `template`_ (e.g. ``'template0'``) from which to create the test
|
||
database.
|
||
|
||
.. _template: https://www.postgresql.org/docs/current/static/sql-createdatabase.html
|
||
|
||
.. setting:: TEST_CREATE
|
||
|
||
``CREATE_DB``
|
||
^^^^^^^^^^^^^
|
||
|
||
Default: ``True``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
If it is set to ``False``, the test tablespaces won't be automatically created
|
||
at the beginning of the tests or dropped at the end.
|
||
|
||
.. setting:: TEST_USER_CREATE
|
||
|
||
``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 the
|
||
beginning of the tests and dropped at the end.
|
||
|
||
.. setting:: TEST_USER
|
||
|
||
``USER``
|
||
^^^^^^^^
|
||
|
||
Default: ``None``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The username to use when connecting to the Oracle database that will be used
|
||
when running tests. If not provided, Django will use ``'test_' + USER``.
|
||
|
||
.. setting:: TEST_PASSWD
|
||
|
||
``PASSWORD``
|
||
^^^^^^^^^^^^
|
||
|
||
Default: ``None``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The password to use when connecting to the Oracle database that will be used
|
||
when running tests. If not provided, Django will generate a random password.
|
||
|
||
.. setting:: TEST_TBLSPACE
|
||
|
||
``TBLSPACE``
|
||
^^^^^^^^^^^^
|
||
|
||
Default: ``None``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The name of the tablespace that will be used when running tests. If not
|
||
provided, Django will use ``'test_' + USER``.
|
||
|
||
.. setting:: TEST_TBLSPACE_TMP
|
||
|
||
``TBLSPACE_TMP``
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
Default: ``None``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The name of the temporary tablespace that will be used when running tests. If
|
||
not provided, Django will use ``'test_' + USER + '_temp'``.
|
||
|
||
.. setting:: DATAFILE
|
||
|
||
``DATAFILE``
|
||
^^^^^^^^^^^^
|
||
|
||
Default: ``None``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The name of the datafile to use for the TBLSPACE. If not provided, Django will
|
||
use ``TBLSPACE + '.dbf'``.
|
||
|
||
.. setting:: DATAFILE_TMP
|
||
|
||
``DATAFILE_TMP``
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
Default: ``None``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The name of the datafile to use for the TBLSPACE_TMP. If not provided, Django
|
||
will use ``TBLSPACE_TMP + '.dbf'``.
|
||
|
||
.. setting:: DATAFILE_MAXSIZE
|
||
|
||
``DATAFILE_MAXSIZE``
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Default: ``'500M'``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The maximum size that the DATAFILE is allowed to grow to.
|
||
|
||
.. setting:: DATAFILE_TMP_MAXSIZE
|
||
|
||
``DATAFILE_TMP_MAXSIZE``
|
||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Default: ``'500M'``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The maximum size that the DATAFILE_TMP is allowed to grow to.
|
||
|
||
.. setting:: DATAFILE_SIZE
|
||
|
||
``DATAFILE_SIZE``
|
||
^^^^^^^^^^^^^^^^^
|
||
|
||
.. versionadded:: 2.0
|
||
|
||
Default: ``'50M'``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The initial size of the DATAFILE.
|
||
|
||
.. setting:: DATAFILE_TMP_SIZE
|
||
|
||
``DATAFILE_TMP_SIZE``
|
||
^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
.. versionadded:: 2.0
|
||
|
||
Default: ``'50M'``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The initial size of the DATAFILE_TMP.
|
||
|
||
.. setting:: DATAFILE_EXTSIZE
|
||
|
||
``DATAFILE_EXTSIZE``
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
.. versionadded:: 2.0
|
||
|
||
Default: ``'25M'``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The amount by which the DATAFILE is extended when more space is required.
|
||
|
||
.. setting:: DATAFILE_TMP_EXTSIZE
|
||
|
||
``DATAFILE_TMP_EXTSIZE``
|
||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
.. versionadded:: 2.0
|
||
|
||
Default: ``'25M'``
|
||
|
||
This is an Oracle-specific setting.
|
||
|
||
The amount by which the DATAFILE_TMP is extended when more space is required.
|
||
|
||
.. setting:: DATA_UPLOAD_MAX_MEMORY_SIZE
|
||
|
||
DATA_UPLOAD_MAX_MEMORY_SIZE
|
||
---------------------------
|
||
|
||
Default: ``2621440`` (i.e. 2.5 MB).
|
||
|
||
The maximum size in bytes that a request body may be before a
|
||
:exc:`~django.core.exceptions.SuspiciousOperation` (``RequestDataTooBig``) is
|
||
raised. The check is done when accessing ``request.body`` or ``request.POST``
|
||
and is calculated against the total request size excluding any file upload
|
||
data. You can set this to ``None`` to disable the check. Applications that are
|
||
expected to receive unusually large form posts should tune this setting.
|
||
|
||
The amount of request data is correlated to the amount of memory needed to
|
||
process the request and populate the GET and POST dictionaries. Large requests
|
||
could be used as a denial-of-service attack vector if left unchecked. Since web
|
||
servers don't typically perform deep request inspection, it's not possible to
|
||
perform a similar check at that level.
|
||
|
||
See also :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`.
|
||
|
||
.. setting:: DATA_UPLOAD_MAX_NUMBER_FIELDS
|
||
|
||
DATA_UPLOAD_MAX_NUMBER_FIELDS
|
||
-----------------------------
|
||
|
||
Default: ``1000``
|
||
|
||
The maximum number of parameters that may be received via GET or POST before a
|
||
:exc:`~django.core.exceptions.SuspiciousOperation` (``TooManyFields``) is
|
||
raised. You can set this to ``None`` to disable the check. Applications that
|
||
are expected to receive an unusually large number of form fields should tune
|
||
this setting.
|
||
|
||
The number of request parameters is correlated to the amount of time needed to
|
||
process the request and populate the GET and POST dictionaries. Large requests
|
||
could be used as a denial-of-service attack vector if left unchecked. Since web
|
||
servers don't typically perform deep request inspection, it's not possible to
|
||
perform a similar check at that level.
|
||
|
||
.. setting:: DATABASE_ROUTERS
|
||
|
||
``DATABASE_ROUTERS``
|
||
--------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
The list of routers that will be used to determine which database
|
||
to use when performing a database query.
|
||
|
||
See the documentation on :ref:`automatic database routing in multi
|
||
database configurations <topics-db-multi-db-routing>`.
|
||
|
||
.. setting:: DATE_FORMAT
|
||
|
||
``DATE_FORMAT``
|
||
---------------
|
||
|
||
Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``)
|
||
|
||
The default formatting to use for displaying date fields in any part of the
|
||
system. Note that if :setting:`USE_L10N` is set to ``True``, then the
|
||
locale-dictated format has higher precedence and will be applied instead. See
|
||
:tfilter:`allowed date format strings <date>`.
|
||
|
||
See also :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT` and :setting:`SHORT_DATE_FORMAT`.
|
||
|
||
.. setting:: DATE_INPUT_FORMATS
|
||
|
||
``DATE_INPUT_FORMATS``
|
||
----------------------
|
||
|
||
Default::
|
||
|
||
[
|
||
'%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
|
||
'%b %d %Y', '%b %d, %Y', # 'Oct 25 2006', 'Oct 25, 2006'
|
||
'%d %b %Y', '%d %b, %Y', # '25 Oct 2006', '25 Oct, 2006'
|
||
'%B %d %Y', '%B %d, %Y', # 'October 25 2006', 'October 25, 2006'
|
||
'%d %B %Y', '%d %B, %Y', # '25 October 2006', '25 October, 2006'
|
||
]
|
||
|
||
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 these
|
||
format strings use Python's :ref:`datetime module syntax
|
||
<strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
|
||
template filter.
|
||
|
||
When :setting:`USE_L10N` is ``True``, the locale-dictated format has higher
|
||
precedence and will be applied instead.
|
||
|
||
See also :setting:`DATETIME_INPUT_FORMATS` and :setting:`TIME_INPUT_FORMATS`.
|
||
|
||
.. setting:: DATETIME_FORMAT
|
||
|
||
``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 the
|
||
system. Note that if :setting:`USE_L10N` is set to ``True``, then the
|
||
locale-dictated format has higher precedence and will be applied instead. See
|
||
:tfilter:`allowed date format strings <date>`.
|
||
|
||
See also :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT` and :setting:`SHORT_DATETIME_FORMAT`.
|
||
|
||
.. setting:: DATETIME_INPUT_FORMATS
|
||
|
||
``DATETIME_INPUT_FORMATS``
|
||
--------------------------
|
||
|
||
Default::
|
||
|
||
[
|
||
'%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59'
|
||
'%Y-%m-%d %H:%M:%S.%f', # '2006-10-25 14:30:59.000200'
|
||
'%Y-%m-%d %H:%M', # '2006-10-25 14:30'
|
||
'%Y-%m-%d', # '2006-10-25'
|
||
'%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59'
|
||
'%m/%d/%Y %H:%M:%S.%f', # '10/25/2006 14:30:59.000200'
|
||
'%m/%d/%Y %H:%M', # '10/25/2006 14:30'
|
||
'%m/%d/%Y', # '10/25/2006'
|
||
'%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59'
|
||
'%m/%d/%y %H:%M:%S.%f', # '10/25/06 14:30:59.000200'
|
||
'%m/%d/%y %H:%M', # '10/25/06 14:30'
|
||
'%m/%d/%y', # '10/25/06'
|
||
]
|
||
|
||
A list of formats that will be accepted when inputting data on a datetime
|
||
field. Formats will be tried in order, using the first valid one. Note that
|
||
these format strings use Python's :ref:`datetime module syntax
|
||
<strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
|
||
template filter.
|
||
|
||
When :setting:`USE_L10N` is ``True``, the locale-dictated format has higher
|
||
precedence and will be applied instead.
|
||
|
||
See also :setting:`DATE_INPUT_FORMATS` and :setting:`TIME_INPUT_FORMATS`.
|
||
|
||
.. setting:: DEBUG
|
||
|
||
``DEBUG``
|
||
---------
|
||
|
||
Default: ``False``
|
||
|
||
A boolean that turns on/off debug mode.
|
||
|
||
Never deploy a site into production with :setting:`DEBUG` turned on.
|
||
|
||
Did you catch that? NEVER deploy a site into production with :setting:`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 :setting:`DEBUG` is ``True``, Django will
|
||
display a detailed traceback, including a lot of metadata about your
|
||
environment, such as all the currently defined Django settings (from
|
||
``settings.py``).
|
||
|
||
As a security measure, Django will *not* include settings that might be
|
||
sensitive, such as :setting:`SECRET_KEY`. Specifically, it will exclude any
|
||
setting 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 output
|
||
that are inappropriate for public consumption. File paths, configuration
|
||
options and the like all give attackers extra information about your server.
|
||
|
||
It is also important to remember that when running with :setting:`DEBUG`
|
||
turned on, Django will remember every SQL query it executes. This is useful
|
||
when you're debugging, but it'll rapidly consume memory on a production server.
|
||
|
||
Finally, if :setting:`DEBUG` is ``False``, you also need to properly set
|
||
the :setting:`ALLOWED_HOSTS` setting. Failing to do so will result in all
|
||
requests being returned as "Bad Request (400)".
|
||
|
||
.. note::
|
||
|
||
The default :file:`settings.py` file created by :djadmin:`django-admin
|
||
startproject <startproject>` sets ``DEBUG = True`` for convenience.
|
||
|
||
.. _django/views/debug.py: https://github.com/django/django/blob/master/django/views/debug.py
|
||
|
||
.. setting:: DEBUG_PROPAGATE_EXCEPTIONS
|
||
|
||
``DEBUG_PROPAGATE_EXCEPTIONS``
|
||
------------------------------
|
||
|
||
Default: ``False``
|
||
|
||
If set to ``True``, Django's exception handling of view functions
|
||
(:data:`~django.conf.urls.handler500`, or the debug view if :setting:`DEBUG`
|
||
is ``True``) and logging of 500 responses (:ref:`django-request-logger`) is
|
||
skipped and exceptions propagate upwards.
|
||
|
||
This can be useful for some test setups. It shouldn't be used on a live site
|
||
unless you want your web server (instead of Django) to generate "Internal
|
||
Server Error" responses. In that case, make sure your server doesn't show the
|
||
stack trace or other sensitive information in the response.
|
||
|
||
.. setting:: DECIMAL_SEPARATOR
|
||
|
||
``DECIMAL_SEPARATOR``
|
||
---------------------
|
||
|
||
Default: ``'.'`` (Dot)
|
||
|
||
Default decimal separator used when formatting decimal numbers.
|
||
|
||
Note that if :setting:`USE_L10N` is set to ``True``, then the locale-dictated
|
||
format has higher precedence and will be applied instead.
|
||
|
||
See also :setting:`NUMBER_GROUPING`, :setting:`THOUSAND_SEPARATOR` and
|
||
:setting:`USE_THOUSAND_SEPARATOR`.
|
||
|
||
|
||
.. setting:: DEFAULT_CHARSET
|
||
|
||
``DEFAULT_CHARSET``
|
||
-------------------
|
||
|
||
Default: ``'utf-8'``
|
||
|
||
Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't
|
||
manually specified. Used with :setting:`DEFAULT_CONTENT_TYPE` to construct the
|
||
``Content-Type`` header.
|
||
|
||
.. setting:: DEFAULT_CONTENT_TYPE
|
||
|
||
``DEFAULT_CONTENT_TYPE``
|
||
------------------------
|
||
|
||
Default: ``'text/html'``
|
||
|
||
Default content type to use for all ``HttpResponse`` objects, if a MIME type
|
||
isn't manually specified. Used with :setting:`DEFAULT_CHARSET` to construct
|
||
the ``Content-Type`` header.
|
||
|
||
.. deprecated:: 2.0
|
||
|
||
This setting is deprecated because it doesn't interact well with
|
||
third-party apps and is obsolete since HTML5 has mostly superseded XHTML.
|
||
|
||
.. setting:: DEFAULT_EXCEPTION_REPORTER_FILTER
|
||
|
||
``DEFAULT_EXCEPTION_REPORTER_FILTER``
|
||
-------------------------------------
|
||
|
||
Default: ``'``:class:`django.views.debug.SafeExceptionReporterFilter`\ ``'``
|
||
|
||
Default exception reporter filter class to be used if none has been assigned to
|
||
the :class:`~django.http.HttpRequest` instance yet.
|
||
See :ref:`Filtering error reports<filtering-error-reports>`.
|
||
|
||
.. setting:: DEFAULT_FILE_STORAGE
|
||
|
||
``DEFAULT_FILE_STORAGE``
|
||
------------------------
|
||
|
||
Default: ``'``:class:`django.core.files.storage.FileSystemStorage`\ ``'``
|
||
|
||
Default file storage class to be used for any file-related operations that don't
|
||
specify a particular storage system. See :doc:`/topics/files`.
|
||
|
||
.. setting:: DEFAULT_FROM_EMAIL
|
||
|
||
``DEFAULT_FROM_EMAIL``
|
||
----------------------
|
||
|
||
Default: ``'webmaster@localhost'``
|
||
|
||
Default email address to use for various automated correspondence from the
|
||
site manager(s). This doesn't include error messages sent to :setting:`ADMINS`
|
||
and :setting:`MANAGERS`; for that, see :setting:`SERVER_EMAIL`.
|
||
|
||
.. setting:: DEFAULT_INDEX_TABLESPACE
|
||
|
||
``DEFAULT_INDEX_TABLESPACE``
|
||
----------------------------
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
Default tablespace to use for indexes on fields that don't specify
|
||
one, if the backend supports it (see :doc:`/topics/db/tablespaces`).
|
||
|
||
.. setting:: DEFAULT_TABLESPACE
|
||
|
||
``DEFAULT_TABLESPACE``
|
||
----------------------
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
Default tablespace to use for models that don't specify one, if the
|
||
backend supports it (see :doc:`/topics/db/tablespaces`).
|
||
|
||
.. setting:: DISALLOWED_USER_AGENTS
|
||
|
||
``DISALLOWED_USER_AGENTS``
|
||
--------------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
List of compiled regular expression objects representing User-Agent strings that
|
||
are not allowed to visit any page, systemwide. Use this for bad robots/crawlers.
|
||
This is only used if ``CommonMiddleware`` is installed (see
|
||
:doc:`/topics/http/middleware`).
|
||
|
||
.. setting:: EMAIL_BACKEND
|
||
|
||
``EMAIL_BACKEND``
|
||
-----------------
|
||
|
||
Default: ``'``:class:`django.core.mail.backends.smtp.EmailBackend`\ ``'``
|
||
|
||
The backend to use for sending emails. For the list of available backends see
|
||
:doc:`/topics/email`.
|
||
|
||
.. setting:: EMAIL_FILE_PATH
|
||
|
||
``EMAIL_FILE_PATH``
|
||
-------------------
|
||
|
||
Default: Not defined
|
||
|
||
The directory used by the ``file`` email backend to store output files.
|
||
|
||
.. setting:: EMAIL_HOST
|
||
|
||
``EMAIL_HOST``
|
||
--------------
|
||
|
||
Default: ``'localhost'``
|
||
|
||
The host to use for sending email.
|
||
|
||
See also :setting:`EMAIL_PORT`.
|
||
|
||
.. setting:: EMAIL_HOST_PASSWORD
|
||
|
||
``EMAIL_HOST_PASSWORD``
|
||
-----------------------
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
Password to use for the SMTP server defined in :setting:`EMAIL_HOST`. This
|
||
setting is used in conjunction with :setting:`EMAIL_HOST_USER` when
|
||
authenticating to the SMTP server. If either of these settings is empty,
|
||
Django won't attempt authentication.
|
||
|
||
See also :setting:`EMAIL_HOST_USER`.
|
||
|
||
.. setting:: EMAIL_HOST_USER
|
||
|
||
``EMAIL_HOST_USER``
|
||
-------------------
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
Username to use for the SMTP server defined in :setting:`EMAIL_HOST`.
|
||
If empty, Django won't attempt authentication.
|
||
|
||
See also :setting:`EMAIL_HOST_PASSWORD`.
|
||
|
||
.. setting:: EMAIL_PORT
|
||
|
||
``EMAIL_PORT``
|
||
--------------
|
||
|
||
Default: ``25``
|
||
|
||
Port to use for the SMTP server defined in :setting:`EMAIL_HOST`.
|
||
|
||
.. setting:: EMAIL_SUBJECT_PREFIX
|
||
|
||
``EMAIL_SUBJECT_PREFIX``
|
||
------------------------
|
||
|
||
Default: ``'[Django] '``
|
||
|
||
Subject-line prefix for email messages sent with ``django.core.mail.mail_admins``
|
||
or ``django.core.mail.mail_managers``. You'll probably want to include the
|
||
trailing space.
|
||
|
||
.. setting:: EMAIL_USE_LOCALTIME
|
||
|
||
``EMAIL_USE_LOCALTIME``
|
||
-----------------------
|
||
|
||
Default: ``False``
|
||
|
||
Whether to send the SMTP ``Date`` header of email messages in the local time
|
||
zone (``True``) or in UTC (``False``).
|
||
|
||
.. setting:: EMAIL_USE_TLS
|
||
|
||
``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 are
|
||
experiencing hanging connections, see the implicit TLS setting
|
||
:setting:`EMAIL_USE_SSL`.
|
||
|
||
.. setting:: EMAIL_USE_SSL
|
||
|
||
``EMAIL_USE_SSL``
|
||
-----------------
|
||
|
||
Default: ``False``
|
||
|
||
Whether to use an implicit TLS (secure) connection when talking to the SMTP
|
||
server. In most email documentation this type of TLS connection is referred
|
||
to as SSL. It is generally used on port 465. If you are experiencing problems,
|
||
see the explicit TLS setting :setting:`EMAIL_USE_TLS`.
|
||
|
||
Note that :setting:`EMAIL_USE_TLS`/:setting:`EMAIL_USE_SSL` are mutually
|
||
exclusive, so only set one of those settings to ``True``.
|
||
|
||
.. setting:: EMAIL_SSL_CERTFILE
|
||
|
||
``EMAIL_SSL_CERTFILE``
|
||
----------------------
|
||
|
||
Default: ``None``
|
||
|
||
If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True``, you can
|
||
optionally specify the path to a PEM-formatted certificate chain file to use
|
||
for the SSL connection.
|
||
|
||
.. setting:: EMAIL_SSL_KEYFILE
|
||
|
||
``EMAIL_SSL_KEYFILE``
|
||
---------------------
|
||
|
||
Default: ``None``
|
||
|
||
If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True``, you can
|
||
optionally specify the path to a PEM-formatted private key file to use for the
|
||
SSL connection.
|
||
|
||
Note that setting :setting:`EMAIL_SSL_CERTFILE` and :setting:`EMAIL_SSL_KEYFILE`
|
||
doesn't result in any certificate checking. They're passed to the underlying SSL
|
||
connection. Please refer to the documentation of Python's
|
||
:func:`python:ssl.wrap_socket` function for details on how the certificate chain
|
||
file and private key file are handled.
|
||
|
||
.. setting:: EMAIL_TIMEOUT
|
||
|
||
``EMAIL_TIMEOUT``
|
||
-----------------
|
||
|
||
Default: ``None``
|
||
|
||
Specifies a timeout in seconds for blocking operations like the connection
|
||
attempt.
|
||
|
||
.. setting:: FILE_CHARSET
|
||
|
||
``FILE_CHARSET``
|
||
----------------
|
||
|
||
Default: ``'utf-8'``
|
||
|
||
The character encoding used to decode any files read from disk. This includes
|
||
template files and initial SQL data files.
|
||
|
||
.. setting:: FILE_UPLOAD_HANDLERS
|
||
|
||
``FILE_UPLOAD_HANDLERS``
|
||
------------------------
|
||
|
||
Default::
|
||
|
||
[
|
||
'django.core.files.uploadhandler.MemoryFileUploadHandler',
|
||
'django.core.files.uploadhandler.TemporaryFileUploadHandler',
|
||
]
|
||
|
||
A list of handlers to use for uploading. Changing this setting allows complete
|
||
customization -- even replacement -- of Django's upload process.
|
||
|
||
See :doc:`/topics/files` for details.
|
||
|
||
.. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE
|
||
|
||
``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 to
|
||
the file system. See :doc:`/topics/files` for details.
|
||
|
||
See also :setting:`DATA_UPLOAD_MAX_MEMORY_SIZE`.
|
||
|
||
.. setting:: FILE_UPLOAD_DIRECTORY_PERMISSIONS
|
||
|
||
``FILE_UPLOAD_DIRECTORY_PERMISSIONS``
|
||
-------------------------------------
|
||
|
||
Default: ``None``
|
||
|
||
The numeric mode to apply to directories created in the process of uploading
|
||
files.
|
||
|
||
This setting also determines the default permissions for collected static
|
||
directories when using the :djadmin:`collectstatic` management command. See
|
||
:djadmin:`collectstatic` for details on overriding it.
|
||
|
||
This value mirrors the functionality and caveats of the
|
||
:setting:`FILE_UPLOAD_PERMISSIONS` setting.
|
||
|
||
.. setting:: FILE_UPLOAD_PERMISSIONS
|
||
|
||
``FILE_UPLOAD_PERMISSIONS``
|
||
---------------------------
|
||
|
||
Default: ``None``
|
||
|
||
The numeric mode (i.e. ``0o644``) to set newly uploaded files to. For
|
||
more information about what these modes mean, see the documentation for
|
||
:func:`os.chmod`.
|
||
|
||
If this isn't given or is ``None``, you'll get operating-system
|
||
dependent behavior. On most platforms, temporary files will have a mode
|
||
of ``0o600``, and files saved from memory will be saved using the
|
||
system's standard umask.
|
||
|
||
For security reasons, these permissions aren't applied to the temporary files
|
||
that are stored in :setting:`FILE_UPLOAD_TEMP_DIR`.
|
||
|
||
This setting also determines the default permissions for collected static files
|
||
when using the :djadmin:`collectstatic` management command. See
|
||
:djadmin:`collectstatic` 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 leading
|
||
``0`` is very important: it indicates an octal number, which is the
|
||
way that modes must be specified. If you try to use ``644``, you'll
|
||
get totally incorrect behavior.
|
||
|
||
.. setting:: FILE_UPLOAD_TEMP_DIR
|
||
|
||
``FILE_UPLOAD_TEMP_DIR``
|
||
------------------------
|
||
|
||
Default: ``None``
|
||
|
||
The directory to store data to (typically files larger than
|
||
:setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`) temporarily while uploading files.
|
||
If ``None``, Django will use the standard temporary directory for the operating
|
||
system. For example, this will default to ``/tmp`` on \*nix-style operating
|
||
systems.
|
||
|
||
See :doc:`/topics/files` for details.
|
||
|
||
.. setting:: FIRST_DAY_OF_WEEK
|
||
|
||
``FIRST_DAY_OF_WEEK``
|
||
---------------------
|
||
|
||
Default: ``0`` (Sunday)
|
||
|
||
A number representing the first day of the week. This is especially useful
|
||
when displaying a calendar. This value is only used when not using
|
||
format internationalization, or when a format cannot be found for the
|
||
current locale.
|
||
|
||
The value must be an integer from 0 to 6, where 0 means Sunday, 1 means
|
||
Monday and so on.
|
||
|
||
.. setting:: FIXTURE_DIRS
|
||
|
||
``FIXTURE_DIRS``
|
||
----------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
List of directories searched for fixture files, in addition to the
|
||
``fixtures`` directory of each application, in search order.
|
||
|
||
Note that these paths should use Unix-style forward slashes, even on Windows.
|
||
|
||
See :ref:`initial-data-via-fixtures` and :ref:`topics-testing-fixtures`.
|
||
|
||
.. setting:: FORCE_SCRIPT_NAME
|
||
|
||
``FORCE_SCRIPT_NAME``
|
||
---------------------
|
||
|
||
Default: ``None``
|
||
|
||
If not ``None``, this will be used as the value of the ``SCRIPT_NAME``
|
||
environment variable in any HTTP request. This setting can be used to override
|
||
the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version
|
||
of the preferred value or not supplied at all. It is also used by
|
||
:func:`django.setup()` to set the URL resolver script prefix outside of the
|
||
request/response cycle (e.g. in management commands and standalone scripts) to
|
||
generate correct URLs when ``SCRIPT_NAME`` is not ``/``.
|
||
|
||
.. setting:: FORM_RENDERER
|
||
|
||
``FORM_RENDERER``
|
||
-----------------
|
||
|
||
Default: ``'``:class:`django.forms.renderers.DjangoTemplates`\ ``'``
|
||
|
||
The class that renders form widgets. It must implement :ref:`the low-level
|
||
render API <low-level-widget-render-api>`.
|
||
|
||
.. setting:: FORMAT_MODULE_PATH
|
||
|
||
``FORMAT_MODULE_PATH``
|
||
----------------------
|
||
|
||
Default: ``None``
|
||
|
||
A full Python path to a Python package that contains format definitions for
|
||
project locales. If not ``None``, Django will check for a ``formats.py``
|
||
file, under the directory named as the current locale, and will use the
|
||
formats defined in this file.
|
||
|
||
For example, if :setting:`FORMAT_MODULE_PATH` is set to ``mysite.formats``,
|
||
and current language is ``en`` (English), Django will expect a directory tree
|
||
like::
|
||
|
||
mysite/
|
||
formats/
|
||
__init__.py
|
||
en/
|
||
__init__.py
|
||
formats.py
|
||
|
||
You can also set this setting to a list of Python paths, for example::
|
||
|
||
FORMAT_MODULE_PATH = [
|
||
'mysite.formats',
|
||
'some_app.formats',
|
||
]
|
||
|
||
When Django searches for a certain format, it will go through all given Python
|
||
paths until it finds a module that actually defines the given format. This
|
||
means that formats defined in packages farther up in the list will take
|
||
precedence over the same formats in packages farther down.
|
||
|
||
Available formats are :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT`,
|
||
:setting:`DATETIME_FORMAT`, :setting:`YEAR_MONTH_FORMAT`,
|
||
:setting:`MONTH_DAY_FORMAT`, :setting:`SHORT_DATE_FORMAT`,
|
||
:setting:`SHORT_DATETIME_FORMAT`, :setting:`FIRST_DAY_OF_WEEK`,
|
||
:setting:`DECIMAL_SEPARATOR`, :setting:`THOUSAND_SEPARATOR` and
|
||
:setting:`NUMBER_GROUPING`.
|
||
|
||
.. setting:: IGNORABLE_404_URLS
|
||
|
||
``IGNORABLE_404_URLS``
|
||
----------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
List of compiled regular expression objects describing URLs that should be
|
||
ignored when reporting HTTP 404 errors via email (see
|
||
:doc:`/howto/error-reporting`). Regular expressions are matched against
|
||
:meth:`request's full paths <django.http.HttpRequest.get_full_path>` (including
|
||
query string, if any). Use this if your site does not provide a commonly
|
||
requested file such as ``favicon.ico`` or ``robots.txt``, or if it gets
|
||
hammered by script kiddies.
|
||
|
||
This is only used if
|
||
:class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled (see
|
||
:doc:`/topics/http/middleware`).
|
||
|
||
.. setting:: INSTALLED_APPS
|
||
|
||
``INSTALLED_APPS``
|
||
------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
A list of strings designating all applications that are enabled in this
|
||
Django installation. Each string should be a dotted Python path to:
|
||
|
||
* an application configuration class (preferred), or
|
||
* a package containing an application.
|
||
|
||
:doc:`Learn more about application configurations </ref/applications>`.
|
||
|
||
.. admonition:: Use the application registry for introspection
|
||
|
||
Your code should never access :setting:`INSTALLED_APPS` directly. Use
|
||
:attr:`django.apps.apps` instead.
|
||
|
||
.. admonition:: Application names and labels must be unique in
|
||
:setting:`INSTALLED_APPS`
|
||
|
||
Application :attr:`names <django.apps.AppConfig.name>` — the dotted Python
|
||
path to the application package — must be unique. There is no way to
|
||
include the same application twice, short of duplicating its code under
|
||
another name.
|
||
|
||
Application :attr:`labels <django.apps.AppConfig.label>` — by default the
|
||
final part of the name — must be unique too. For example, you can't
|
||
include both ``django.contrib.auth`` and ``myproject.auth``. However, you
|
||
can relabel an application with a custom configuration that defines a
|
||
different :attr:`~django.apps.AppConfig.label`.
|
||
|
||
These rules apply regardless of whether :setting:`INSTALLED_APPS`
|
||
references application configuration classes or application packages.
|
||
|
||
When several applications provide different versions of the same resource
|
||
(template, static file, management command, translation), the application
|
||
listed first in :setting:`INSTALLED_APPS` has precedence.
|
||
|
||
.. setting:: INTERNAL_IPS
|
||
|
||
``INTERNAL_IPS``
|
||
----------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
A list of IP addresses, as strings, that:
|
||
|
||
* Allow the :func:`~django.template.context_processors.debug` context processor
|
||
to add some variables to the template context.
|
||
* Can use the :ref:`admindocs bookmarklets <admindocs-bookmarklets>` even if
|
||
not logged in as a staff user.
|
||
* Are marked as "internal" (as opposed to "EXTERNAL") in
|
||
:class:`~django.utils.log.AdminEmailHandler` emails.
|
||
|
||
.. setting:: LANGUAGE_CODE
|
||
|
||
``LANGUAGE_CODE``
|
||
-----------------
|
||
|
||
Default: ``'en-us'``
|
||
|
||
A string representing the language code for this installation. This should be in
|
||
standard :term:`language ID format <language code>`. For example, U.S. English
|
||
is ``"en-us"``. See also the `list of language identifiers`_ and
|
||
:doc:`/topics/i18n/index`.
|
||
|
||
:setting:`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 served
|
||
to all users.
|
||
* If the locale middleware is active, it provides a fallback language in case the
|
||
user's preferred language can't be determined or is not supported by the
|
||
website. It also provides the fallback translation when a translation for a
|
||
given literal doesn't exist for the user's preferred language.
|
||
|
||
See :ref:`how-django-discovers-language-preference` for more details.
|
||
|
||
.. _list of language identifiers: http://www.i18nguy.com/unicode/language-identifiers.html
|
||
|
||
.. setting:: LANGUAGE_COOKIE_AGE
|
||
|
||
``LANGUAGE_COOKIE_AGE``
|
||
-----------------------
|
||
|
||
Default: ``None`` (expires at browser close)
|
||
|
||
The age of the language cookie, in seconds.
|
||
|
||
.. setting:: LANGUAGE_COOKIE_DOMAIN
|
||
|
||
``LANGUAGE_COOKIE_DOMAIN``
|
||
--------------------------
|
||
|
||
Default: ``None``
|
||
|
||
The domain to use for the language cookie. Set this to a string such as
|
||
``".example.com"`` (note the leading dot!) for cross-domain cookies, or use
|
||
``None`` for a standard domain cookie.
|
||
|
||
Be cautious when updating this setting on a production site. If you update
|
||
this setting to enable cross-domain cookies on a site that previously used
|
||
standard domain cookies, existing user cookies that have the old domain
|
||
will not be updated. This will result in site users being unable to switch
|
||
the language as long as these cookies persist. The only safe and reliable
|
||
option to perform the switch is to change the language cookie name
|
||
permanently (via the :setting:`LANGUAGE_COOKIE_NAME` setting) and to add
|
||
a middleware that copies the value from the old cookie to a new one and then
|
||
deletes the old one.
|
||
|
||
.. setting:: LANGUAGE_COOKIE_NAME
|
||
|
||
``LANGUAGE_COOKIE_NAME``
|
||
------------------------
|
||
|
||
Default: ``'django_language'``
|
||
|
||
The name of the cookie to use for the language cookie. This can be whatever
|
||
you want (as long as it's different from the other cookie names in your
|
||
application). See :doc:`/topics/i18n/index`.
|
||
|
||
.. setting:: LANGUAGE_COOKIE_PATH
|
||
|
||
``LANGUAGE_COOKIE_PATH``
|
||
------------------------
|
||
|
||
Default: ``'/'``
|
||
|
||
The path set on the language cookie. This should either match the URL path of your
|
||
Django installation or be a parent of that path.
|
||
|
||
This is useful if you have multiple Django instances running under the same
|
||
hostname. They can use different cookie paths and each instance will only see
|
||
its own language cookie.
|
||
|
||
Be cautious when updating this setting on a production site. If you update this
|
||
setting to use a deeper path than it previously used, existing user cookies that
|
||
have the old path will not be updated. This will result in site users being
|
||
unable to switch the language as long as these cookies persist. The only safe
|
||
and reliable option to perform the switch is to change the language cookie name
|
||
permanently (via the :setting:`LANGUAGE_COOKIE_NAME` setting), and to add
|
||
a middleware that copies the value from the old cookie to a new one and then
|
||
deletes the one.
|
||
|
||
.. setting:: LANGUAGES
|
||
|
||
``LANGUAGES``
|
||
-------------
|
||
|
||
Default: A list of all available languages. This list is continually growing
|
||
and including a copy here would inevitably become rapidly out of date. You can
|
||
see the current list of translated languages by looking in
|
||
``django/conf/global_settings.py`` (or view the `online source`_).
|
||
|
||
.. _online source: https://github.com/django/django/blob/master/django/conf/global_settings.py
|
||
|
||
The list is a list of two-tuples in the format
|
||
(:term:`language code<language code>`, ``language name``) -- for example,
|
||
``('ja', 'Japanese')``.
|
||
This specifies which languages are available for language selection. See
|
||
:doc:`/topics/i18n/index`.
|
||
|
||
Generally, the default value should suffice. Only set this setting if you want
|
||
to restrict language selection to a subset of the Django-provided languages.
|
||
|
||
If you define a custom :setting:`LANGUAGES` setting, you can mark the
|
||
language names as translation strings using the
|
||
:func:`~django.utils.translation.gettext_lazy` function.
|
||
|
||
Here's a sample settings file::
|
||
|
||
from django.utils.translation import gettext_lazy as _
|
||
|
||
LANGUAGES = [
|
||
('de', _('German')),
|
||
('en', _('English')),
|
||
]
|
||
|
||
.. setting:: LOCALE_PATHS
|
||
|
||
``LOCALE_PATHS``
|
||
----------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
A list of directories where Django looks for translation files.
|
||
See :ref:`how-django-discovers-translations`.
|
||
|
||
Example::
|
||
|
||
LOCALE_PATHS = [
|
||
'/home/www/project/common_files/locale',
|
||
'/var/local/translations/locale',
|
||
]
|
||
|
||
Django will look within each of these paths for the ``<locale_code>/LC_MESSAGES``
|
||
directories containing the actual translation files.
|
||
|
||
.. setting:: LOGGING
|
||
|
||
``LOGGING``
|
||
-----------
|
||
|
||
Default: A logging configuration dictionary.
|
||
|
||
A data structure containing configuration information. The contents of
|
||
this data structure will be passed as the argument to the
|
||
configuration method described in :setting:`LOGGING_CONFIG`.
|
||
|
||
Among other things, the default logging configuration passes HTTP 500 server
|
||
errors to an email log handler when :setting:`DEBUG` is ``False``. See also
|
||
:ref:`configuring-logging`.
|
||
|
||
You can see the default logging configuration by looking in
|
||
``django/utils/log.py`` (or view the `online source`__).
|
||
|
||
__ https://github.com/django/django/blob/master/django/utils/log.py
|
||
|
||
.. setting:: LOGGING_CONFIG
|
||
|
||
``LOGGING_CONFIG``
|
||
------------------
|
||
|
||
Default: ``'logging.config.dictConfig'``
|
||
|
||
A path to a callable that will be used to configure logging in the
|
||
Django project. Points at a instance of Python's :ref:`dictConfig
|
||
<logging-config-dictschema>` configuration method by default.
|
||
|
||
If you set :setting:`LOGGING_CONFIG` to ``None``, the logging
|
||
configuration process will be skipped.
|
||
|
||
.. setting:: MANAGERS
|
||
|
||
``MANAGERS``
|
||
------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
A list in the same format as :setting:`ADMINS` that specifies who should get
|
||
broken link notifications when
|
||
:class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled.
|
||
|
||
.. setting:: MEDIA_ROOT
|
||
|
||
``MEDIA_ROOT``
|
||
--------------
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
Absolute filesystem path to the directory that will hold :doc:`user-uploaded
|
||
files </topics/files>`.
|
||
|
||
Example: ``"/var/www/example.com/media/"``
|
||
|
||
See also :setting:`MEDIA_URL`.
|
||
|
||
.. warning::
|
||
|
||
:setting:`MEDIA_ROOT` and :setting:`STATIC_ROOT` must have different
|
||
values. Before :setting:`STATIC_ROOT` was introduced, it was common to
|
||
rely or fallback on :setting:`MEDIA_ROOT` to also serve static files;
|
||
however, since this can have serious security implications, there is a
|
||
validation check to prevent it.
|
||
|
||
.. setting:: MEDIA_URL
|
||
|
||
``MEDIA_URL``
|
||
-------------
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
URL that handles the media served from :setting:`MEDIA_ROOT`, used
|
||
for :doc:`managing stored files </topics/files>`. It must end in a slash if set
|
||
to a non-empty value. You will need to :ref:`configure these files to be served
|
||
<serving-uploaded-files-in-development>` in both development and production
|
||
environments.
|
||
|
||
If you want to use ``{{ MEDIA_URL }}`` in your templates, add
|
||
``'django.template.context_processors.media'`` in the ``'context_processors'``
|
||
option of :setting:`TEMPLATES`.
|
||
|
||
Example: ``"http://media.example.com/"``
|
||
|
||
.. warning::
|
||
|
||
There are security risks if you are accepting uploaded content from
|
||
untrusted users! See the security guide's topic on
|
||
:ref:`user-uploaded-content-security` for mitigation details.
|
||
|
||
.. warning::
|
||
|
||
:setting:`MEDIA_URL` and :setting:`STATIC_URL` must have different
|
||
values. See :setting:`MEDIA_ROOT` for more details.
|
||
|
||
.. setting:: MIDDLEWARE
|
||
|
||
``MIDDLEWARE``
|
||
--------------
|
||
|
||
Default: ``None``
|
||
|
||
A list of middleware to use. See :doc:`/topics/http/middleware`.
|
||
|
||
.. setting:: MIGRATION_MODULES
|
||
|
||
``MIGRATION_MODULES``
|
||
---------------------
|
||
|
||
Default: ``{}`` (Empty dictionary)
|
||
|
||
A dictionary specifying the package where migration modules can be found on a
|
||
per-app basis. The default value of this setting is an empty dictionary, but
|
||
the default package name for migration modules is ``migrations``.
|
||
|
||
Example::
|
||
|
||
{'blog': 'blog.db_migrations'}
|
||
|
||
In this case, migrations pertaining to the ``blog`` app will be contained in
|
||
the ``blog.db_migrations`` package.
|
||
|
||
If you provide the ``app_label`` argument, :djadmin:`makemigrations` will
|
||
automatically create the package if it doesn't already exist.
|
||
|
||
When you supply ``None`` as a value for an app, Django will consider the app as
|
||
an app without migrations regardless of an existing ``migrations`` submodule.
|
||
This can be used, for example, in a test settings file to skip migrations while
|
||
testing (tables will still be created for the apps' models). If this is used in
|
||
your general project settings, remember to use the :option:`migrate
|
||
--run-syncdb` option if you want to create tables for the app.
|
||
|
||
.. setting:: MONTH_DAY_FORMAT
|
||
|
||
``MONTH_DAY_FORMAT``
|
||
--------------------
|
||
|
||
Default: ``'F j'``
|
||
|
||
The default formatting to use for date fields on Django admin change-list
|
||
pages -- and, possibly, by other parts of the system -- in cases when only the
|
||
month and day are displayed.
|
||
|
||
For example, when a Django admin change-list page is being filtered by a date
|
||
drilldown, the header for a given day displays the day and month. Different
|
||
locales have different formats. For example, U.S. English would say
|
||
"January 1," whereas Spanish might say "1 Enero."
|
||
|
||
Note that if :setting:`USE_L10N` is set to ``True``, then the corresponding
|
||
locale-dictated format has higher precedence and will be applied.
|
||
|
||
See :tfilter:`allowed date format strings <date>`. See also
|
||
:setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`,
|
||
:setting:`TIME_FORMAT` and :setting:`YEAR_MONTH_FORMAT`.
|
||
|
||
.. setting:: NUMBER_GROUPING
|
||
|
||
``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``, then
|
||
no grouping will be applied to the number. If this setting is greater than
|
||
``0``, then :setting:`THOUSAND_SEPARATOR` will be used as the separator between
|
||
those groups.
|
||
|
||
Some locales use non-uniform digit grouping, e.g. ``10,00,00,000`` in
|
||
``en_IN``. For this case, you can provide a sequence with the number of digit
|
||
group sizes to be applied. The first number defines the size of the group
|
||
preceding the decimal delimiter, and each number that follows defines the size
|
||
of preceding groups. If the sequence is terminated with ``-1``, no further
|
||
grouping is performed. If the sequence terminates with a ``0``, the last group
|
||
size is used for the remainder of the number.
|
||
|
||
Example tuple for ``en_IN``::
|
||
|
||
NUMBER_GROUPING = (3, 2, 0)
|
||
|
||
Note that if :setting:`USE_L10N` is set to ``True``, then the locale-dictated
|
||
format has higher precedence and will be applied instead.
|
||
|
||
See also :setting:`DECIMAL_SEPARATOR`, :setting:`THOUSAND_SEPARATOR` and
|
||
:setting:`USE_THOUSAND_SEPARATOR`.
|
||
|
||
.. setting:: PREPEND_WWW
|
||
|
||
``PREPEND_WWW``
|
||
---------------
|
||
|
||
Default: ``False``
|
||
|
||
Whether to prepend the "www." subdomain to URLs that don't have it. This is only
|
||
used if :class:`~django.middleware.common.CommonMiddleware` is installed
|
||
(see :doc:`/topics/http/middleware`). See also :setting:`APPEND_SLASH`.
|
||
|
||
.. setting:: ROOT_URLCONF
|
||
|
||
``ROOT_URLCONF``
|
||
----------------
|
||
|
||
Default: Not defined
|
||
|
||
A string representing the full Python import path to your root URLconf. For example:
|
||
``"mydjangoapps.urls"``. Can be overridden on a per-request basis by
|
||
setting the attribute ``urlconf`` on the incoming ``HttpRequest``
|
||
object. See :ref:`how-django-processes-a-request` for details.
|
||
|
||
.. setting:: SECRET_KEY
|
||
|
||
``SECRET_KEY``
|
||
--------------
|
||
|
||
Default: ``''`` (Empty string)
|
||
|
||
A secret key for a particular Django installation. This is used to provide
|
||
:doc:`cryptographic signing </topics/signing>`, and should be set to a unique,
|
||
unpredictable value.
|
||
|
||
:djadmin:`django-admin startproject <startproject>` automatically adds a
|
||
randomly-generated ``SECRET_KEY`` to each new project.
|
||
|
||
Uses of the key shouldn't assume that it's text or bytes. Every use should go
|
||
through :func:`~django.utils.encoding.force_text` or
|
||
:func:`~django.utils.encoding.force_bytes` to convert it to the desired type.
|
||
|
||
Django will refuse to start if :setting:`SECRET_KEY` is not set.
|
||
|
||
.. warning::
|
||
|
||
**Keep this value secret.**
|
||
|
||
Running Django with a known :setting:`SECRET_KEY` defeats many of Django's
|
||
security protections, and can lead to privilege escalation and remote code
|
||
execution vulnerabilities.
|
||
|
||
The secret key is used for:
|
||
|
||
* All :doc:`sessions </topics/http/sessions>` if you are using
|
||
any other session backend than ``django.contrib.sessions.backends.cache``,
|
||
or are using the default
|
||
:meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()`.
|
||
* All :doc:`messages </ref/contrib/messages>` if you are using
|
||
:class:`~django.contrib.messages.storage.cookie.CookieStorage` or
|
||
:class:`~django.contrib.messages.storage.fallback.FallbackStorage`.
|
||
* All :class:`~django.contrib.auth.views.PasswordResetView` tokens.
|
||
* Any usage of :doc:`cryptographic signing </topics/signing>`, unless a
|
||
different key is provided.
|
||
|
||
If you rotate your secret key, all of the above will be invalidated.
|
||
Secret keys are not used for passwords of users and key rotation will not
|
||
affect them.
|
||
|
||
.. note::
|
||
|
||
The default :file:`settings.py` file created by :djadmin:`django-admin
|
||
startproject <startproject>` creates a unique ``SECRET_KEY`` for
|
||
convenience.
|
||
|
||
.. setting:: SECURE_BROWSER_XSS_FILTER
|
||
|
||
``SECURE_BROWSER_XSS_FILTER``
|
||
-----------------------------
|
||
|
||
Default: ``False``
|
||
|
||
If ``True``, the :class:`~django.middleware.security.SecurityMiddleware` sets
|
||
the :ref:`x-xss-protection` header on all responses that do not already have it.
|
||
|
||
.. setting:: SECURE_CONTENT_TYPE_NOSNIFF
|
||
|
||
``SECURE_CONTENT_TYPE_NOSNIFF``
|
||
-------------------------------
|
||
|
||
Default: ``False``
|
||
|
||
If ``True``, the :class:`~django.middleware.security.SecurityMiddleware`
|
||
sets the :ref:`x-content-type-options` header on all responses that do not
|
||
already have it.
|
||
|
||
.. setting:: SECURE_HSTS_INCLUDE_SUBDOMAINS
|
||
|
||
``SECURE_HSTS_INCLUDE_SUBDOMAINS``
|
||
----------------------------------
|
||
|
||
Default: ``False``
|
||
|
||
If ``True``, the :class:`~django.middleware.security.SecurityMiddleware` adds
|
||
the ``includeSubDomains`` directive to the :ref:`http-strict-transport-security`
|
||
header. It has no effect unless :setting:`SECURE_HSTS_SECONDS` is set to a
|
||
non-zero value.
|
||
|
||
.. warning::
|
||
Setting this incorrectly can irreversibly (for the value of
|
||
:setting:`SECURE_HSTS_SECONDS`) break your site. Read the
|
||
:ref:`http-strict-transport-security` documentation first.
|
||
|
||
.. setting:: SECURE_HSTS_PRELOAD
|
||
|
||
``SECURE_HSTS_PRELOAD``
|
||
-----------------------
|
||
|
||
Default: ``False``
|
||
|
||
If ``True``, the :class:`~django.middleware.security.SecurityMiddleware` adds
|
||
the ``preload`` directive to the :ref:`http-strict-transport-security`
|
||
header. It has no effect unless :setting:`SECURE_HSTS_SECONDS` is set to a
|
||
non-zero value.
|
||
|
||
.. setting:: SECURE_HSTS_SECONDS
|
||
|
||
``SECURE_HSTS_SECONDS``
|
||
-----------------------
|
||
|
||
Default: ``0``
|
||
|
||
If set to a non-zero integer value, the
|
||
:class:`~django.middleware.security.SecurityMiddleware` sets the
|
||
:ref:`http-strict-transport-security` header on all responses that do not
|
||
already have it.
|
||
|
||
.. warning::
|
||
Setting this incorrectly can irreversibly (for some time) break your site.
|
||
Read the :ref:`http-strict-transport-security` documentation first.
|
||
|
||
.. setting:: SECURE_PROXY_SSL_HEADER
|
||
|
||
``SECURE_PROXY_SSL_HEADER``
|
||
---------------------------
|
||
|
||
Default: ``None``
|
||
|
||
A tuple representing a HTTP header/value combination that signifies a request
|
||
is secure. This controls the behavior of the request object's ``is_secure()``
|
||
method.
|
||
|
||
This takes some explanation. By default, ``is_secure()`` is able to determine
|
||
whether a request is secure by looking at whether the requested URL uses
|
||
"https://". This is important for Django's CSRF protection, and 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" the
|
||
fact that a request is HTTPS, using a non-HTTPS connection between the proxy
|
||
and Django. In this case, ``is_secure()`` would always return ``False`` -- even
|
||
for requests that were made via HTTPS by the end user.
|
||
|
||
In this situation, you'll want to configure your proxy to set a custom HTTP
|
||
header that tells Django whether the request came in via HTTPS, and you'll want
|
||
to set ``SECURE_PROXY_SSL_HEADER`` so that Django knows what header to look
|
||
for.
|
||
|
||
You'll need to set a tuple with two elements -- the name of the header to look
|
||
for and the required value. For example::
|
||
|
||
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
|
||
|
||
Here, we're telling Django that we trust the ``X-Forwarded-Proto`` header
|
||
that comes from our proxy, and any time its value is ``'https'``, then the
|
||
request is guaranteed to be secure (i.e., it originally came in via HTTPS).
|
||
Obviously, you should *only* set this setting if you control your proxy or
|
||
have some other guarantee 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 automatically
|
||
adds ``'HTTP_'`` to the start of x-header names before making the header
|
||
available in ``request.META``.)
|
||
|
||
.. warning::
|
||
|
||
**You will probably open security holes in your site if you set this
|
||
without knowing what you're doing. And if you fail to set it when you
|
||
should. Seriously.**
|
||
|
||
Make sure ALL of the following are true before setting this (assuming the
|
||
values from the example above):
|
||
|
||
* Your Django app is behind a proxy.
|
||
* Your proxy strips the ``X-Forwarded-Proto`` header from all incoming
|
||
requests. In other words, if end users include that header in their
|
||
requests, 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 ``None``
|
||
and find another way of determining HTTPS, perhaps via custom middleware.
|
||
|
||
.. setting:: SECURE_REDIRECT_EXEMPT
|
||
|
||
``SECURE_REDIRECT_EXEMPT``
|
||
--------------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
If a URL path matches a regular expression in this list, the request will not be
|
||
redirected to HTTPS. If :setting:`SECURE_SSL_REDIRECT` is ``False``, this
|
||
setting has no effect.
|
||
|
||
.. setting:: SECURE_SSL_HOST
|
||
|
||
``SECURE_SSL_HOST``
|
||
-------------------
|
||
|
||
Default: ``None``
|
||
|
||
If a string (e.g. ``secure.example.com``), all SSL redirects will be directed
|
||
to this host rather than the originally-requested host
|
||
(e.g. ``www.example.com``). If :setting:`SECURE_SSL_REDIRECT` is ``False``, this
|
||
setting has no effect.
|
||
|
||
.. setting:: SECURE_SSL_REDIRECT
|
||
|
||
``SECURE_SSL_REDIRECT``
|
||
-----------------------
|
||
|
||
Default: ``False``
|
||
|
||
If ``True``, the :class:`~django.middleware.security.SecurityMiddleware`
|
||
:ref:`redirects <ssl-redirect>` all non-HTTPS requests to HTTPS (except for
|
||
those URLs matching a regular expression listed in
|
||
:setting:`SECURE_REDIRECT_EXEMPT`).
|
||
|
||
.. note::
|
||
|
||
If turning this to ``True`` causes infinite redirects, it probably means
|
||
your site is running behind a proxy and can't tell which requests are secure
|
||
and which are not. Your proxy likely sets a header to indicate secure
|
||
requests; you can correct the problem by finding out what that header is and
|
||
configuring the :setting:`SECURE_PROXY_SSL_HEADER` setting accordingly.
|
||
|
||
.. setting:: SERIALIZATION_MODULES
|
||
|
||
``SERIALIZATION_MODULES``
|
||
-------------------------
|
||
|
||
Default: Not defined
|
||
|
||
A dictionary of modules containing serializer definitions (provided as
|
||
strings), keyed by a string identifier for that serialization type. For
|
||
example, to define a YAML serializer, use::
|
||
|
||
SERIALIZATION_MODULES = {'yaml': 'path.to.yaml_serializer'}
|
||
|
||
.. setting:: SERVER_EMAIL
|
||
|
||
``SERVER_EMAIL``
|
||
----------------
|
||
|
||
Default: ``'root@localhost'``
|
||
|
||
The email address that error messages come from, such as those sent to
|
||
:setting:`ADMINS` and :setting:`MANAGERS`.
|
||
|
||
.. admonition:: Why are my emails sent from a different address?
|
||
|
||
This address is used only for error messages. It is *not* the address that
|
||
regular email messages sent with :meth:`~django.core.mail.send_mail()`
|
||
come from; for that, see :setting:`DEFAULT_FROM_EMAIL`.
|
||
|
||
.. setting:: SHORT_DATE_FORMAT
|
||
|
||
``SHORT_DATE_FORMAT``
|
||
---------------------
|
||
|
||
Default: ``'m/d/Y'`` (e.g. ``12/31/2003``)
|
||
|
||
An available formatting that can be used for displaying date fields on
|
||
templates. Note that if :setting:`USE_L10N` is set to ``True``, then the
|
||
corresponding locale-dictated format has higher precedence and will be applied.
|
||
See :tfilter:`allowed date format strings <date>`.
|
||
|
||
See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATETIME_FORMAT`.
|
||
|
||
.. setting:: 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 on
|
||
templates. Note that if :setting:`USE_L10N` is set to ``True``, then the
|
||
corresponding locale-dictated format has higher precedence and will be applied.
|
||
See :tfilter:`allowed date format strings <date>`.
|
||
|
||
See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATE_FORMAT`.
|
||
|
||
.. setting:: SIGNING_BACKEND
|
||
|
||
``SIGNING_BACKEND``
|
||
-------------------
|
||
|
||
Default: ``'django.core.signing.TimestampSigner'``
|
||
|
||
The backend used for signing cookies and other data.
|
||
|
||
See also the :doc:`/topics/signing` documentation.
|
||
|
||
.. setting:: SILENCED_SYSTEM_CHECKS
|
||
|
||
``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 :doc:`/ref/checks` documentation.
|
||
|
||
.. setting:: TEMPLATES
|
||
|
||
``TEMPLATES``
|
||
-------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
A list containing the settings for all template engines to be used with
|
||
Django. Each item of the list is a dictionary containing the options for an
|
||
individual engine.
|
||
|
||
Here's a simple setup that tells the Django template engine to load templates
|
||
from the ``templates`` subdirectory inside each installed application::
|
||
|
||
TEMPLATES = [
|
||
{
|
||
'BACKEND': 'django.template.backends.django.DjangoTemplates',
|
||
'APP_DIRS': True,
|
||
},
|
||
]
|
||
|
||
The following options are available for all backends.
|
||
|
||
.. setting:: TEMPLATES-BACKEND
|
||
|
||
``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 setting
|
||
``BACKEND`` to a fully-qualified path (i.e. ``'mypackage.whatever.Backend'``).
|
||
|
||
.. setting:: TEMPLATES-NAME
|
||
|
||
``NAME``
|
||
~~~~~~~~
|
||
|
||
Default: see below
|
||
|
||
The alias for this particular template engine. It's an identifier that allows
|
||
selecting an engine for rendering. Aliases must be unique across all
|
||
configured template engines.
|
||
|
||
It defaults to the name of the module defining the engine class, i.e. the
|
||
next to last piece of :setting:`BACKEND <TEMPLATES-BACKEND>`, when it isn't
|
||
provided. For example if the backend is ``'mypackage.whatever.Backend'`` then
|
||
its default name is ``'whatever'``.
|
||
|
||
.. setting:: TEMPLATES-DIRS
|
||
|
||
``DIRS``
|
||
~~~~~~~~
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
Directories where the engine should look for template source files, in search
|
||
order.
|
||
|
||
.. setting:: TEMPLATES-APP_DIRS
|
||
|
||
``APP_DIRS``
|
||
~~~~~~~~~~~~
|
||
|
||
Default: ``False``
|
||
|
||
Whether the engine should look for template source files inside installed
|
||
applications.
|
||
|
||
.. note::
|
||
|
||
The default :file:`settings.py` file created by :djadmin:`django-admin
|
||
startproject <startproject>` sets ``'APP_DIRS': True``.
|
||
|
||
.. setting:: TEMPLATES-OPTIONS
|
||
|
||
``OPTIONS``
|
||
~~~~~~~~~~~
|
||
|
||
Default: ``{}`` (Empty dict)
|
||
|
||
Extra parameters to pass to the template backend. Available parameters vary
|
||
depending on the template backend. See
|
||
:class:`~django.template.backends.django.DjangoTemplates` and
|
||
:class:`~django.template.backends.jinja2.Jinja2` for the options of the
|
||
built-in backends.
|
||
|
||
.. setting:: TEST_RUNNER
|
||
|
||
``TEST_RUNNER``
|
||
---------------
|
||
|
||
Default: ``'django.test.runner.DiscoverRunner'``
|
||
|
||
The name of the class to use for starting the test suite. See
|
||
:ref:`other-testing-frameworks`.
|
||
|
||
.. setting:: TEST_NON_SERIALIZED_APPS
|
||
|
||
``TEST_NON_SERIALIZED_APPS``
|
||
----------------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
In order to restore the database state between tests for
|
||
``TransactionTestCase``\s and database backends without transactions, Django
|
||
will :ref:`serialize the contents of all apps <test-case-serialized-rollback>`
|
||
when it starts the test run so it can then reload from that copy before running
|
||
tests that need it.
|
||
|
||
This slows down the startup time of the test runner; if you have apps that
|
||
you know don't need this feature, you can add their full names in here (e.g.
|
||
``'django.contrib.contenttypes'``) to exclude them from this serialization
|
||
process.
|
||
|
||
.. setting:: THOUSAND_SEPARATOR
|
||
|
||
``THOUSAND_SEPARATOR``
|
||
----------------------
|
||
|
||
Default: ``','`` (Comma)
|
||
|
||
Default thousand separator used when formatting numbers. This setting is
|
||
used only when :setting:`USE_THOUSAND_SEPARATOR` is ``True`` and
|
||
:setting:`NUMBER_GROUPING` is greater than ``0``.
|
||
|
||
Note that if :setting:`USE_L10N` is set to ``True``, then the locale-dictated
|
||
format has higher precedence and will be applied instead.
|
||
|
||
See also :setting:`NUMBER_GROUPING`, :setting:`DECIMAL_SEPARATOR` and
|
||
:setting:`USE_THOUSAND_SEPARATOR`.
|
||
|
||
.. setting:: TIME_FORMAT
|
||
|
||
``TIME_FORMAT``
|
||
---------------
|
||
|
||
Default: ``'P'`` (e.g. ``4 p.m.``)
|
||
|
||
The default formatting to use for displaying time fields in any part of the
|
||
system. Note that if :setting:`USE_L10N` is set to ``True``, then the
|
||
locale-dictated format has higher precedence and will be applied instead. See
|
||
:tfilter:`allowed date format strings <date>`.
|
||
|
||
See also :setting:`DATE_FORMAT` and :setting:`DATETIME_FORMAT`.
|
||
|
||
.. setting:: TIME_INPUT_FORMATS
|
||
|
||
``TIME_INPUT_FORMATS``
|
||
----------------------
|
||
|
||
Default::
|
||
|
||
[
|
||
'%H:%M:%S', # '14:30:59'
|
||
'%H:%M:%S.%f', # '14:30:59.000200'
|
||
'%H:%M', # '14:30'
|
||
]
|
||
|
||
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 these
|
||
format strings use Python's :ref:`datetime module syntax
|
||
<strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
|
||
template filter.
|
||
|
||
When :setting:`USE_L10N` is ``True``, the locale-dictated format has higher
|
||
precedence and will be applied instead.
|
||
|
||
See also :setting:`DATE_INPUT_FORMATS` and :setting:`DATETIME_INPUT_FORMATS`.
|
||
|
||
.. setting:: TIME_ZONE
|
||
|
||
``TIME_ZONE``
|
||
-------------
|
||
|
||
Default: ``'America/Chicago'``
|
||
|
||
A string representing the time zone for this installation. See the `list of
|
||
time zones`_.
|
||
|
||
.. note::
|
||
Since Django was first released with the :setting:`TIME_ZONE` set to
|
||
``'America/Chicago'``, the global setting (used if nothing is defined in
|
||
your project's ``settings.py``) remains ``'America/Chicago'`` for backwards
|
||
compatibility. New project templates default to ``'UTC'``.
|
||
|
||
Note that this isn't necessarily the time zone of the server. For example, one
|
||
server may serve multiple Django-powered sites, each with a separate time zone
|
||
setting.
|
||
|
||
When :setting:`USE_TZ` is ``False``, this is the time zone in which Django
|
||
will store all datetimes. When :setting:`USE_TZ` is ``True``, this is the
|
||
default time zone that Django will use to display datetimes in templates and
|
||
to interpret datetimes entered in forms.
|
||
|
||
On Unix environments (where :func:`time.tzset` is implemented), Django sets the
|
||
``os.environ['TZ']`` variable to the time zone you specify in the
|
||
:setting:`TIME_ZONE` setting. Thus, all your views and models will
|
||
automatically operate in this time zone. However, Django won't set the ``TZ``
|
||
environment variable if you're using the manual configuration option as
|
||
described in :ref:`manually configuring settings
|
||
<settings-without-django-settings-module>`. If Django doesn't set the ``TZ``
|
||
environment variable, it's up to you to ensure your processes are running in
|
||
the correct environment.
|
||
|
||
.. note::
|
||
Django cannot reliably use alternate time zones in a Windows environment.
|
||
If you're running Django on Windows, :setting:`TIME_ZONE` must be set to
|
||
match the system time zone.
|
||
|
||
.. _list of time zones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
|
||
|
||
.. setting:: USE_I18N
|
||
|
||
``USE_I18N``
|
||
------------
|
||
|
||
Default: ``True``
|
||
|
||
A boolean that specifies whether Django's translation system should be enabled.
|
||
This provides an easy way to turn it off, for performance. If this is set to
|
||
``False``, Django will make some optimizations so as not to load the
|
||
translation machinery.
|
||
|
||
See also :setting:`LANGUAGE_CODE`, :setting:`USE_L10N` and :setting:`USE_TZ`.
|
||
|
||
.. note::
|
||
|
||
The default :file:`settings.py` file created by :djadmin:`django-admin
|
||
startproject <startproject>` includes ``USE_I18N = True`` for convenience.
|
||
|
||
.. setting:: USE_L10N
|
||
|
||
``USE_L10N``
|
||
------------
|
||
|
||
Default: ``False``
|
||
|
||
A boolean that specifies if localized formatting of data will be enabled by
|
||
default or not. If this is set to ``True``, e.g. Django will display numbers and
|
||
dates using the format of the current locale.
|
||
|
||
See also :setting:`LANGUAGE_CODE`, :setting:`USE_I18N` and :setting:`USE_TZ`.
|
||
|
||
.. note::
|
||
|
||
The default :file:`settings.py` file created by :djadmin:`django-admin
|
||
startproject <startproject>` includes ``USE_L10N = True`` for convenience.
|
||
|
||
.. setting:: USE_THOUSAND_SEPARATOR
|
||
|
||
``USE_THOUSAND_SEPARATOR``
|
||
--------------------------
|
||
|
||
Default: ``False``
|
||
|
||
A boolean that specifies whether to display numbers using a thousand separator.
|
||
When :setting:`USE_L10N` is set to ``True`` and if this is also set to
|
||
``True``, Django will use the values of :setting:`THOUSAND_SEPARATOR` and
|
||
:setting:`NUMBER_GROUPING` to format numbers unless the locale already has an
|
||
existing thousands separator. If there is a thousands separator in the locale
|
||
format, it will have higher precedence and will be applied instead.
|
||
|
||
See also :setting:`DECIMAL_SEPARATOR`, :setting:`NUMBER_GROUPING` and
|
||
:setting:`THOUSAND_SEPARATOR`.
|
||
|
||
.. setting:: USE_TZ
|
||
|
||
``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 :setting:`TIME_ZONE`, :setting:`USE_I18N` and :setting:`USE_L10N`.
|
||
|
||
.. note::
|
||
|
||
The default :file:`settings.py` file created by
|
||
:djadmin:`django-admin startproject <startproject>` includes
|
||
``USE_TZ = True`` for convenience.
|
||
|
||
.. setting:: USE_X_FORWARDED_HOST
|
||
|
||
``USE_X_FORWARDED_HOST``
|
||
------------------------
|
||
|
||
Default: ``False``
|
||
|
||
A boolean that specifies whether to use the ``X-Forwarded-Host`` header in
|
||
preference to the ``Host`` header. This should only be enabled if a proxy
|
||
which sets this header is in use.
|
||
|
||
This setting takes priority over :setting:`USE_X_FORWARDED_PORT`. Per
|
||
:rfc:`7239#page-7`, the ``X-Forwarded-Host`` header can include the port
|
||
number, in which case you shouldn't use :setting:`USE_X_FORWARDED_PORT`.
|
||
|
||
.. setting:: USE_X_FORWARDED_PORT
|
||
|
||
``USE_X_FORWARDED_PORT``
|
||
------------------------
|
||
|
||
Default: ``False``
|
||
|
||
A boolean that specifies whether to use the ``X-Forwarded-Port`` header in
|
||
preference to the ``SERVER_PORT`` ``META`` variable. This should only be
|
||
enabled if a proxy which sets this header is in use.
|
||
|
||
:setting:`USE_X_FORWARDED_HOST` takes priority over this setting.
|
||
|
||
.. setting:: WSGI_APPLICATION
|
||
|
||
``WSGI_APPLICATION``
|
||
--------------------
|
||
|
||
Default: ``None``
|
||
|
||
The full Python path of the WSGI application object that Django's built-in
|
||
servers (e.g. :djadmin:`runserver`) will use. The :djadmin:`django-admin
|
||
startproject <startproject>` management command will create a simple
|
||
``wsgi.py`` file with an ``application`` callable in it, and point this setting
|
||
to that ``application``.
|
||
|
||
If not set, the return value of ``django.core.wsgi.get_wsgi_application()``
|
||
will be used. In this case, the behavior of :djadmin:`runserver` will be
|
||
identical to previous Django versions.
|
||
|
||
.. setting:: YEAR_MONTH_FORMAT
|
||
|
||
``YEAR_MONTH_FORMAT``
|
||
---------------------
|
||
|
||
Default: ``'F Y'``
|
||
|
||
The default formatting to use for date fields on Django admin change-list
|
||
pages -- and, possibly, by other parts of the system -- in cases when only the
|
||
year and month are displayed.
|
||
|
||
For example, when a Django admin change-list page is being filtered by a date
|
||
drilldown, 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 :setting:`USE_L10N` is set to ``True``, then the corresponding
|
||
locale-dictated format has higher precedence and will be applied.
|
||
|
||
See :tfilter:`allowed date format strings <date>`. See also
|
||
:setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT`
|
||
and :setting:`MONTH_DAY_FORMAT`.
|
||
|
||
.. setting:: X_FRAME_OPTIONS
|
||
|
||
``X_FRAME_OPTIONS``
|
||
-------------------
|
||
|
||
Default: ``'SAMEORIGIN'``
|
||
|
||
The default value for the X-Frame-Options header used by
|
||
:class:`~django.middleware.clickjacking.XFrameOptionsMiddleware`. See the
|
||
:doc:`clickjacking protection </ref/clickjacking/>` documentation.
|
||
|
||
|
||
Auth
|
||
====
|
||
|
||
Settings for :mod:`django.contrib.auth`.
|
||
|
||
.. setting:: AUTHENTICATION_BACKENDS
|
||
|
||
``AUTHENTICATION_BACKENDS``
|
||
---------------------------
|
||
|
||
Default: ``['django.contrib.auth.backends.ModelBackend']``
|
||
|
||
A list of authentication backend classes (as strings) to use when attempting to
|
||
authenticate a user. See the :ref:`authentication backends documentation
|
||
<authentication-backends>` for details.
|
||
|
||
.. setting:: AUTH_USER_MODEL
|
||
|
||
``AUTH_USER_MODEL``
|
||
-------------------
|
||
|
||
Default: ``'auth.User'``
|
||
|
||
The model to use to represent a User. See :ref:`auth-custom-user`.
|
||
|
||
.. warning::
|
||
You cannot change the AUTH_USER_MODEL setting during the lifetime of
|
||
a 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 of
|
||
the app that it lives in.
|
||
See :ref:`auth-custom-user` for more details.
|
||
|
||
.. setting:: LOGIN_REDIRECT_URL
|
||
|
||
``LOGIN_REDIRECT_URL``
|
||
----------------------
|
||
|
||
Default: ``'/accounts/profile/'``
|
||
|
||
The URL where requests are redirected after login when the
|
||
``contrib.auth.login`` view gets no ``next`` parameter.
|
||
|
||
This is used by the :func:`~django.contrib.auth.decorators.login_required`
|
||
decorator, for example.
|
||
|
||
This setting also accepts :ref:`named URL patterns <naming-url-patterns>` which
|
||
can be used to reduce configuration duplication since you don't have to define
|
||
the URL in two places (``settings`` and URLconf).
|
||
|
||
.. setting:: LOGIN_URL
|
||
|
||
``LOGIN_URL``
|
||
-------------
|
||
|
||
Default: ``'/accounts/login/'``
|
||
|
||
The URL where requests are redirected for login, especially when using the
|
||
:func:`~django.contrib.auth.decorators.login_required` decorator.
|
||
|
||
This setting also accepts :ref:`named URL patterns <naming-url-patterns>` which
|
||
can be used to reduce configuration duplication since you don't have to define
|
||
the URL in two places (``settings`` and URLconf).
|
||
|
||
.. setting:: LOGOUT_REDIRECT_URL
|
||
|
||
``LOGOUT_REDIRECT_URL``
|
||
-----------------------
|
||
|
||
Default: ``None``
|
||
|
||
The URL where requests are redirected after a user logs out using
|
||
:class:`~django.contrib.auth.views.LogoutView` (if the view doesn't get a
|
||
``next_page`` argument).
|
||
|
||
If ``None``, no redirect will be performed and the logout view will be
|
||
rendered.
|
||
|
||
This setting also accepts :ref:`named URL patterns <naming-url-patterns>` which
|
||
can be used to reduce configuration duplication since you don't have to define
|
||
the URL in two places (``settings`` and URLconf).
|
||
|
||
.. setting:: PASSWORD_RESET_TIMEOUT_DAYS
|
||
|
||
``PASSWORD_RESET_TIMEOUT_DAYS``
|
||
-------------------------------
|
||
|
||
Default: ``3``
|
||
|
||
The number of days a password reset link is valid for. Used by the
|
||
:mod:`django.contrib.auth` password reset mechanism.
|
||
|
||
.. setting:: PASSWORD_HASHERS
|
||
|
||
``PASSWORD_HASHERS``
|
||
--------------------
|
||
|
||
See :ref:`auth_password_storage`.
|
||
|
||
Default::
|
||
|
||
[
|
||
'django.contrib.auth.hashers.PBKDF2PasswordHasher',
|
||
'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
|
||
'django.contrib.auth.hashers.Argon2PasswordHasher',
|
||
'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
|
||
'django.contrib.auth.hashers.BCryptPasswordHasher',
|
||
]
|
||
|
||
.. setting:: AUTH_PASSWORD_VALIDATORS
|
||
|
||
``AUTH_PASSWORD_VALIDATORS``
|
||
----------------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
The list of validators that are used to check the strength of user's passwords.
|
||
See :ref:`password-validation` for more details. By default, no validation is
|
||
performed and all passwords are accepted.
|
||
|
||
.. _settings-messages:
|
||
|
||
Messages
|
||
========
|
||
|
||
Settings for :mod:`django.contrib.messages`.
|
||
|
||
.. setting:: MESSAGE_LEVEL
|
||
|
||
``MESSAGE_LEVEL``
|
||
-----------------
|
||
|
||
Default: ``messages.INFO``
|
||
|
||
Sets the minimum message level that will be recorded by the messages
|
||
framework. See :ref:`message levels <message-level>` for more details.
|
||
|
||
.. admonition:: Important
|
||
|
||
If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
|
||
the built-in constants, you must import the constants module directly to
|
||
avoid the potential for circular imports, e.g.::
|
||
|
||
from django.contrib.messages import constants as message_constants
|
||
MESSAGE_LEVEL = message_constants.DEBUG
|
||
|
||
If desired, you may specify the numeric values for the constants directly
|
||
according to the values in the above :ref:`constants table
|
||
<message-level-constants>`.
|
||
|
||
.. setting:: MESSAGE_STORAGE
|
||
|
||
``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 :ref:`message storage backends <message-storage-backends>` for more details.
|
||
|
||
The backends that use cookies --
|
||
:class:`~django.contrib.messages.storage.cookie.CookieStorage` and
|
||
:class:`~django.contrib.messages.storage.fallback.FallbackStorage` --
|
||
use the value of :setting:`SESSION_COOKIE_DOMAIN`, :setting:`SESSION_COOKIE_SECURE`
|
||
and :setting:`SESSION_COOKIE_HTTPONLY` when setting their cookies.
|
||
|
||
.. setting:: MESSAGE_TAGS
|
||
|
||
``MESSAGE_TAGS``
|
||
----------------
|
||
|
||
Default::
|
||
|
||
{
|
||
messages.DEBUG: 'debug',
|
||
messages.INFO: 'info',
|
||
messages.SUCCESS: 'success',
|
||
messages.WARNING: 'warning',
|
||
messages.ERROR: 'error',
|
||
}
|
||
|
||
This sets the mapping of message level to message tag, which is typically
|
||
rendered as a CSS class in HTML. If you specify a value, it will extend
|
||
the default. This means you only have to specify those values which you need
|
||
to override. See :ref:`message-displaying` above for more details.
|
||
|
||
.. admonition:: Important
|
||
|
||
If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
|
||
the built-in constants, you must import the ``constants`` module directly to
|
||
avoid the potential for circular imports, e.g.::
|
||
|
||
from django.contrib.messages import constants as message_constants
|
||
MESSAGE_TAGS = {message_constants.INFO: ''}
|
||
|
||
If desired, you may specify the numeric values for the constants directly
|
||
according to the values in the above :ref:`constants table
|
||
<message-level-constants>`.
|
||
|
||
.. _settings-sessions:
|
||
|
||
Sessions
|
||
========
|
||
|
||
Settings for :mod:`django.contrib.sessions`.
|
||
|
||
.. setting:: SESSION_CACHE_ALIAS
|
||
|
||
``SESSION_CACHE_ALIAS``
|
||
-----------------------
|
||
|
||
Default: ``'default'``
|
||
|
||
If you're using :ref:`cache-based session storage <cached-sessions-backend>`,
|
||
this selects the cache to use.
|
||
|
||
.. setting:: SESSION_COOKIE_AGE
|
||
|
||
``SESSION_COOKIE_AGE``
|
||
----------------------
|
||
|
||
Default: ``1209600`` (2 weeks, in seconds)
|
||
|
||
The age of session cookies, in seconds.
|
||
|
||
.. setting:: SESSION_COOKIE_DOMAIN
|
||
|
||
``SESSION_COOKIE_DOMAIN``
|
||
-------------------------
|
||
|
||
Default: ``None``
|
||
|
||
The domain to use for session cookies. Set this to a string such as
|
||
``".example.com"`` (note the leading dot!) for cross-domain cookies, or use
|
||
``None`` for a standard domain cookie.
|
||
|
||
Be cautious when updating this setting on a production site. If you update
|
||
this setting to enable cross-domain cookies on a site that previously used
|
||
standard domain cookies, existing user cookies will be set to the old
|
||
domain. This may result in them being unable to log in as long as these cookies
|
||
persist.
|
||
|
||
This setting also affects cookies set by :mod:`django.contrib.messages`.
|
||
|
||
.. setting:: SESSION_COOKIE_HTTPONLY
|
||
|
||
``SESSION_COOKIE_HTTPONLY``
|
||
---------------------------
|
||
|
||
Default: ``True``
|
||
|
||
Whether to use ``HTTPOnly`` flag on the session cookie. If this is set to
|
||
``True``, client-side JavaScript will not to be able to access the
|
||
session cookie.
|
||
|
||
HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It
|
||
is not part of the :rfc:`2109` standard for cookies, and it isn't honored
|
||
consistently by all browsers. However, when it is honored, it can be a
|
||
useful way to mitigate the risk of a client side script accessing the
|
||
protected cookie data.
|
||
|
||
Turning it on makes it less trivial for an attacker to escalate a cross-site
|
||
scripting vulnerability into full hijacking of a user's session. There's not
|
||
much excuse for leaving this off, either: if your code depends on reading
|
||
session cookies from JavaScript, you're probably doing it wrong.
|
||
|
||
.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly
|
||
|
||
.. setting:: SESSION_COOKIE_NAME
|
||
|
||
``SESSION_COOKIE_NAME``
|
||
-----------------------
|
||
|
||
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).
|
||
|
||
.. setting:: SESSION_COOKIE_PATH
|
||
|
||
``SESSION_COOKIE_PATH``
|
||
-----------------------
|
||
|
||
Default: ``'/'``
|
||
|
||
The path set on the session cookie. This should either match the URL path of your
|
||
Django installation or be parent of that path.
|
||
|
||
This is useful if you have multiple Django instances running under the same
|
||
hostname. They can use different cookie paths, and each instance will only see
|
||
its own session cookie.
|
||
|
||
.. setting:: SESSION_COOKIE_SECURE
|
||
|
||
``SESSION_COOKIE_SECURE``
|
||
-------------------------
|
||
|
||
Default: ``False``
|
||
|
||
Whether to use a secure cookie for the session cookie. If this is set to
|
||
``True``, the cookie will be marked as "secure," which means browsers may
|
||
ensure that the cookie is only sent under an HTTPS connection.
|
||
|
||
Since it's trivial for a packet sniffer (e.g. `Firesheep`_) to hijack a user's
|
||
session if the session cookie is sent unencrypted, there's really no good
|
||
excuse to leave this off. It will prevent you from using sessions on insecure
|
||
requests and that's a good thing.
|
||
|
||
.. _Firesheep: http://codebutler.com/firesheep
|
||
|
||
.. setting:: SESSION_ENGINE
|
||
|
||
``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 :ref:`configuring-sessions` for more details.
|
||
|
||
.. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE
|
||
|
||
``SESSION_EXPIRE_AT_BROWSER_CLOSE``
|
||
-----------------------------------
|
||
|
||
Default: ``False``
|
||
|
||
Whether to expire the session when the user closes their browser. See
|
||
:ref:`browser-length-vs-persistent-sessions`.
|
||
|
||
.. setting:: SESSION_FILE_PATH
|
||
|
||
``SESSION_FILE_PATH``
|
||
---------------------
|
||
|
||
Default: ``None``
|
||
|
||
If you're using file-based session storage, this sets the directory in
|
||
which Django will store session data. When the default value (``None``) is
|
||
used, Django will use the standard temporary directory for the system.
|
||
|
||
|
||
.. setting:: SESSION_SAVE_EVERY_REQUEST
|
||
|
||
``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. Empty
|
||
sessions won't be created, even if this setting is active.
|
||
|
||
.. setting:: SESSION_SERIALIZER
|
||
|
||
``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 :ref:`session_serialization` for details, including a warning regarding
|
||
possible remote code execution when using
|
||
:class:`~django.contrib.sessions.serializers.PickleSerializer`.
|
||
|
||
Sites
|
||
=====
|
||
|
||
Settings for :mod:`django.contrib.sites`.
|
||
|
||
.. setting:: SITE_ID
|
||
|
||
``SITE_ID``
|
||
-----------
|
||
|
||
Default: Not defined
|
||
|
||
The ID, as an integer, of the current site in the ``django_site`` database
|
||
table. This is used so that application data can hook into specific sites
|
||
and a single database can manage content for multiple sites.
|
||
|
||
|
||
.. _settings-staticfiles:
|
||
|
||
Static Files
|
||
============
|
||
|
||
Settings for :mod:`django.contrib.staticfiles`.
|
||
|
||
.. setting:: STATIC_ROOT
|
||
|
||
``STATIC_ROOT``
|
||
---------------
|
||
|
||
Default: ``None``
|
||
|
||
The absolute path to the directory where :djadmin:`collectstatic` will collect
|
||
static files for deployment.
|
||
|
||
Example: ``"/var/www/example.com/static/"``
|
||
|
||
If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
|
||
(as in the default project template), the :djadmin:`collectstatic` management
|
||
command will collect static files into this directory. See the how-to on
|
||
:doc:`managing static files</howto/static-files/index>` for more details about
|
||
usage.
|
||
|
||
.. warning::
|
||
|
||
This should be an initially empty destination directory for collecting
|
||
your static files from their permanent locations into one directory for
|
||
ease of deployment; it is **not** a place to store your static files
|
||
permanently. You should do that in directories that will be found by
|
||
:doc:`staticfiles</ref/contrib/staticfiles>`’s
|
||
:setting:`finders<STATICFILES_FINDERS>`, which by default, are
|
||
``'static/'`` app sub-directories and any directories you include in
|
||
:setting:`STATICFILES_DIRS`).
|
||
|
||
.. setting:: STATIC_URL
|
||
|
||
``STATIC_URL``
|
||
--------------
|
||
|
||
Default: ``None``
|
||
|
||
URL to use when referring to static files located in :setting:`STATIC_ROOT`.
|
||
|
||
Example: ``"/static/"`` or ``"http://static.example.com/"``
|
||
|
||
If not ``None``, this will be used as the base path for
|
||
:ref:`asset definitions<form-asset-paths>` (the ``Media`` class) and the
|
||
:doc:`staticfiles app</ref/contrib/staticfiles>`.
|
||
|
||
It must end in a slash if set to a non-empty value.
|
||
|
||
You may need to :ref:`configure these files to be served in development
|
||
<serving-static-files-in-development>` and will definitely need to do so
|
||
:doc:`in production </howto/static-files/deployment>`.
|
||
|
||
.. setting:: STATICFILES_DIRS
|
||
|
||
``STATICFILES_DIRS``
|
||
--------------------
|
||
|
||
Default: ``[]`` (Empty list)
|
||
|
||
This setting defines the additional locations the staticfiles app will traverse
|
||
if the ``FileSystemFinder`` finder is enabled, e.g. if you use the
|
||
:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
|
||
static file serving view.
|
||
|
||
This should be set to a list of strings that contain full paths to
|
||
your additional files directory(ies) e.g.::
|
||
|
||
STATICFILES_DIRS = [
|
||
"/home/special.polls.com/polls/static",
|
||
"/home/polls.com/polls/static",
|
||
"/opt/webfiles/common",
|
||
]
|
||
|
||
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 additional
|
||
namespace, you can **optionally** provide a prefix as ``(prefix, path)``
|
||
tuples, e.g.::
|
||
|
||
STATICFILES_DIRS = [
|
||
# ...
|
||
("downloads", "/opt/webfiles/stats"),
|
||
]
|
||
|
||
For example, assuming you have :setting:`STATIC_URL` set to ``'/static/'``, the
|
||
:djadmin:`collectstatic` management command would collect the "stats" files
|
||
in a ``'downloads'`` subdirectory of :setting:`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.:
|
||
|
||
.. code-block:: html+django
|
||
|
||
<a href="{% static "downloads/polls_20101022.tar.gz" %}">
|
||
|
||
.. setting:: STATICFILES_STORAGE
|
||
|
||
``STATICFILES_STORAGE``
|
||
-----------------------
|
||
|
||
Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
|
||
|
||
The file storage engine to use when collecting static files with the
|
||
:djadmin:`collectstatic` management command.
|
||
|
||
A ready-to-use instance of the storage backend defined in this setting
|
||
can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``.
|
||
|
||
For an example, see :ref:`staticfiles-from-cdn`.
|
||
|
||
.. setting:: STATICFILES_FINDERS
|
||
|
||
``STATICFILES_FINDERS``
|
||
-----------------------
|
||
|
||
Default::
|
||
|
||
[
|
||
'django.contrib.staticfiles.finders.FileSystemFinder',
|
||
'django.contrib.staticfiles.finders.AppDirectoriesFinder',
|
||
]
|
||
|
||
The list of finder backends that know how to find static files in
|
||
various locations.
|
||
|
||
The default will find files stored in the :setting:`STATICFILES_DIRS` setting
|
||
(using ``django.contrib.staticfiles.finders.FileSystemFinder``) and in a
|
||
``static`` subdirectory of each app (using
|
||
``django.contrib.staticfiles.finders.AppDirectoriesFinder``). If multiple
|
||
files with the same name are present, the first file that is found will be
|
||
used.
|
||
|
||
One finder is disabled by default:
|
||
``django.contrib.staticfiles.finders.DefaultStorageFinder``. If added to
|
||
your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
|
||
the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE`
|
||
setting.
|
||
|
||
.. note::
|
||
|
||
When using the ``AppDirectoriesFinder`` finder, make sure your apps
|
||
can be found by staticfiles. Simply add the app to the
|
||
:setting:`INSTALLED_APPS` setting of your site.
|
||
|
||
Static file finders are currently considered a private interface, and this
|
||
interface is thus undocumented.
|
||
|
||
Core Settings Topical Index
|
||
===========================
|
||
|
||
Cache
|
||
-----
|
||
* :setting:`CACHES`
|
||
* :setting:`CACHE_MIDDLEWARE_ALIAS`
|
||
* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX`
|
||
* :setting:`CACHE_MIDDLEWARE_SECONDS`
|
||
|
||
Database
|
||
--------
|
||
* :setting:`DATABASES`
|
||
* :setting:`DATABASE_ROUTERS`
|
||
* :setting:`DEFAULT_INDEX_TABLESPACE`
|
||
* :setting:`DEFAULT_TABLESPACE`
|
||
|
||
Debugging
|
||
---------
|
||
* :setting:`DEBUG`
|
||
* :setting:`DEBUG_PROPAGATE_EXCEPTIONS`
|
||
|
||
Email
|
||
-----
|
||
* :setting:`ADMINS`
|
||
* :setting:`DEFAULT_CHARSET`
|
||
* :setting:`DEFAULT_FROM_EMAIL`
|
||
* :setting:`EMAIL_BACKEND`
|
||
* :setting:`EMAIL_FILE_PATH`
|
||
* :setting:`EMAIL_HOST`
|
||
* :setting:`EMAIL_HOST_PASSWORD`
|
||
* :setting:`EMAIL_HOST_USER`
|
||
* :setting:`EMAIL_PORT`
|
||
* :setting:`EMAIL_SSL_CERTFILE`
|
||
* :setting:`EMAIL_SSL_KEYFILE`
|
||
* :setting:`EMAIL_SUBJECT_PREFIX`
|
||
* :setting:`EMAIL_TIMEOUT`
|
||
* :setting:`EMAIL_USE_LOCALTIME`
|
||
* :setting:`EMAIL_USE_TLS`
|
||
* :setting:`MANAGERS`
|
||
* :setting:`SERVER_EMAIL`
|
||
|
||
Error reporting
|
||
---------------
|
||
* :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER`
|
||
* :setting:`IGNORABLE_404_URLS`
|
||
* :setting:`MANAGERS`
|
||
* :setting:`SILENCED_SYSTEM_CHECKS`
|
||
|
||
.. _file-upload-settings:
|
||
|
||
File uploads
|
||
------------
|
||
* :setting:`DEFAULT_FILE_STORAGE`
|
||
* :setting:`FILE_CHARSET`
|
||
* :setting:`FILE_UPLOAD_HANDLERS`
|
||
* :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`
|
||
* :setting:`FILE_UPLOAD_PERMISSIONS`
|
||
* :setting:`FILE_UPLOAD_TEMP_DIR`
|
||
* :setting:`MEDIA_ROOT`
|
||
* :setting:`MEDIA_URL`
|
||
|
||
Forms
|
||
-----
|
||
* :setting:`FORM_RENDERER`
|
||
|
||
Globalization (``i18n``/``l10n``)
|
||
---------------------------------
|
||
* :setting:`DATE_FORMAT`
|
||
* :setting:`DATE_INPUT_FORMATS`
|
||
* :setting:`DATETIME_FORMAT`
|
||
* :setting:`DATETIME_INPUT_FORMATS`
|
||
* :setting:`DECIMAL_SEPARATOR`
|
||
* :setting:`FIRST_DAY_OF_WEEK`
|
||
* :setting:`FORMAT_MODULE_PATH`
|
||
* :setting:`LANGUAGE_CODE`
|
||
* :setting:`LANGUAGE_COOKIE_AGE`
|
||
* :setting:`LANGUAGE_COOKIE_DOMAIN`
|
||
* :setting:`LANGUAGE_COOKIE_NAME`
|
||
* :setting:`LANGUAGE_COOKIE_PATH`
|
||
* :setting:`LANGUAGES`
|
||
* :setting:`LOCALE_PATHS`
|
||
* :setting:`MONTH_DAY_FORMAT`
|
||
* :setting:`NUMBER_GROUPING`
|
||
* :setting:`SHORT_DATE_FORMAT`
|
||
* :setting:`SHORT_DATETIME_FORMAT`
|
||
* :setting:`THOUSAND_SEPARATOR`
|
||
* :setting:`TIME_FORMAT`
|
||
* :setting:`TIME_INPUT_FORMATS`
|
||
* :setting:`TIME_ZONE`
|
||
* :setting:`USE_I18N`
|
||
* :setting:`USE_L10N`
|
||
* :setting:`USE_THOUSAND_SEPARATOR`
|
||
* :setting:`USE_TZ`
|
||
* :setting:`YEAR_MONTH_FORMAT`
|
||
|
||
HTTP
|
||
----
|
||
* :setting:`DATA_UPLOAD_MAX_MEMORY_SIZE`
|
||
* :setting:`DATA_UPLOAD_MAX_NUMBER_FIELDS`
|
||
* :setting:`DEFAULT_CHARSET`
|
||
* :setting:`DEFAULT_CONTENT_TYPE`
|
||
* :setting:`DISALLOWED_USER_AGENTS`
|
||
* :setting:`FORCE_SCRIPT_NAME`
|
||
* :setting:`INTERNAL_IPS`
|
||
* :setting:`MIDDLEWARE`
|
||
* Security
|
||
|
||
* :setting:`SECURE_BROWSER_XSS_FILTER`
|
||
* :setting:`SECURE_CONTENT_TYPE_NOSNIFF`
|
||
* :setting:`SECURE_HSTS_INCLUDE_SUBDOMAINS`
|
||
* :setting:`SECURE_HSTS_PRELOAD`
|
||
* :setting:`SECURE_HSTS_SECONDS`
|
||
* :setting:`SECURE_PROXY_SSL_HEADER`
|
||
* :setting:`SECURE_REDIRECT_EXEMPT`
|
||
* :setting:`SECURE_SSL_HOST`
|
||
* :setting:`SECURE_SSL_REDIRECT`
|
||
* :setting:`SIGNING_BACKEND`
|
||
* :setting:`USE_X_FORWARDED_HOST`
|
||
* :setting:`USE_X_FORWARDED_PORT`
|
||
* :setting:`WSGI_APPLICATION`
|
||
|
||
Logging
|
||
-------
|
||
* :setting:`LOGGING`
|
||
* :setting:`LOGGING_CONFIG`
|
||
|
||
Models
|
||
------
|
||
* :setting:`ABSOLUTE_URL_OVERRIDES`
|
||
* :setting:`FIXTURE_DIRS`
|
||
* :setting:`INSTALLED_APPS`
|
||
|
||
Security
|
||
--------
|
||
* Cross Site Request Forgery Protection
|
||
|
||
* :setting:`CSRF_COOKIE_DOMAIN`
|
||
* :setting:`CSRF_COOKIE_NAME`
|
||
* :setting:`CSRF_COOKIE_PATH`
|
||
* :setting:`CSRF_COOKIE_SECURE`
|
||
* :setting:`CSRF_FAILURE_VIEW`
|
||
* :setting:`CSRF_HEADER_NAME`
|
||
* :setting:`CSRF_TRUSTED_ORIGINS`
|
||
* :setting:`CSRF_USE_SESSIONS`
|
||
|
||
* :setting:`SECRET_KEY`
|
||
* :setting:`X_FRAME_OPTIONS`
|
||
|
||
Serialization
|
||
-------------
|
||
* :setting:`DEFAULT_CHARSET`
|
||
* :setting:`SERIALIZATION_MODULES`
|
||
|
||
Templates
|
||
---------
|
||
* :setting:`TEMPLATES`
|
||
|
||
Testing
|
||
-------
|
||
* Database: :setting:`TEST <DATABASE-TEST>`
|
||
* :setting:`TEST_NON_SERIALIZED_APPS`
|
||
* :setting:`TEST_RUNNER`
|
||
|
||
URLs
|
||
----
|
||
* :setting:`APPEND_SLASH`
|
||
* :setting:`PREPEND_WWW`
|
||
* :setting:`ROOT_URLCONF`
|