========

Settings

========

.. contents::

    :local:

    :depth: 1

Available settings

==================

Here's a full list of all available settings, in alphabetical order, and their

default values.

.. 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 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:: ADMIN_FOR

ADMIN_FOR

---------

Default: ``()`` (Empty tuple)

Used for admin-site settings modules, this should be a tuple of settings

modules (in the format ``'foo.bar.baz'``) for which this site is an admin.

The admin site uses this in its automatically-introspected documentation of

models, views and template tags.

.. setting:: ADMIN_MEDIA_PREFIX

ADMIN_MEDIA_PREFIX

------------------

Default: ``'/media/'``

The URL prefix for admin media -- CSS, JavaScript and images used by

the Django administrative interface. Make sure to use a trailing

slash, and to have this be different from the ``MEDIA_URL`` setting

(since the same URL cannot be mapped onto two different sets of

files).

.. setting:: ADMINS

ADMINS

------

Default: ``()`` (Empty tuple)

A tuple that lists people who get code error notifications. When

``DEBUG=False`` and a view raises an exception, Django will e-mail these people

with the full exception information. Each member of the tuple should be a tuple

of (Full name, e-mail address). Example::

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

Note that Django will e-mail *all* of these people whenever an error happens.

See :doc:`/howto/error-reporting` for more information.

.. setting:: ALLOWED_INCLUDE_ROOTS

ALLOWED_INCLUDE_ROOTS

---------------------

Default: ``()`` (Empty tuple)

A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template

tag. This is a security measure, so that template authors can't access files

that they shouldn't be accessing.

For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``,

then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}``

wouldn't.

.. 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 ``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:: AUTHENTICATION_BACKENDS

AUTHENTICATION_BACKENDS

-----------------------

Default: ``('django.contrib.auth.backends.ModelBackend',)``

A tuple of authentication backend classes (as strings) to use when attempting to

authenticate a user. See the :doc:`authentication backends documentation

</ref/authbackends>` for details.

.. setting:: AUTH_PROFILE_MODULE

AUTH_PROFILE_MODULE

-------------------

Default: Not defined

The site-specific user profile model used by this site. See

:ref:`auth-profiles`.

.. setting:: CACHE_BACKEND

CACHE_BACKEND

-------------

Default: ``'locmem://'``

The cache backend to use. See :doc:`/topics/cache`.

.. setting:: CACHE_MIDDLEWARE_ANONYMOUS_ONLY

CACHE_MIDDLEWARE_ANONYMOUS_ONLY

-------------------------------

Default: ``False``

If the value of this setting is ``True``, only anonymous requests (i.e., not

those made by a logged-in user) will be cached.  Otherwise, the middleware

caches every page that doesn't have GET or POST parameters.

If you set the value of this setting to ``True``, you should make sure you've

activated ``AuthenticationMiddleware``.

See the :doc:`cache documentation </topics/cache>` for more information.

.. setting:: CACHE_MIDDLEWARE_KEY_PREFIX

CACHE_MIDDLEWARE_KEY_PREFIX

---------------------------

Default: ``''`` (Empty string)

The cache key prefix that the cache middleware should use. See

:doc:`/topics/cache`.

.. setting:: CACHE_MIDDLEWARE_SECONDS

CACHE_MIDDLEWARE_SECONDS

------------------------

Default: ``600``

The default number of seconds to cache a page when the caching middleware or

``cache_page()`` decorator is used.

.. setting:: CSRF_COOKIE_DOMAIN

CSRF_COOKIE_DOMAIN

------------------

.. versionadded:: 1.2

Default: ``None``

The domain to be used when setting the CSRF cookie.  This can be useful for

allowing cross-subdomain requests to be exluded from the normal cross site

request forgery protection.  It should be set to a string such as

``".lawrence.com"`` to allow a POST request from a form on one subdomain to be

accepted by accepted by a view served from another subdomain.

.. setting:: CSRF_COOKIE_NAME

CSRF_COOKIE_NAME

----------------

.. versionadded:: 1.2

Default: ``'csrftoken'``

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

want.  See :doc:`/ref/contrib/csrf`.

.. setting:: CSRF_FAILURE_VIEW

CSRF_FAILURE_VIEW

-----------------

.. versionadded:: 1.2

Default: ``'django.views.csrf.csrf_failure'``

A dotted path to the view function to be used when an incoming request

is rejected by the CSRF protection.  The function should have this signature::

  def csrf_failure(request, reason="")

where ``reason`` is a short message (intended for developers or logging, not for

end users) indicating the reason the request was rejected.  See

:doc:`/ref/contrib/csrf`.

.. setting:: DATABASES

DATABASES

---------

.. versionadded:: 1.2

Default: ``{}`` (Empty dictionary)

A dictionary containing the settings for all databases to be used with

Django. It is a nested dictionary whose contents maps database aliases

to a dictionary containing the options for an individual database.

The :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'

        }

    }

For other database backends, or more complex SQLite configurations, other options

will be required. The following inner options are available.

.. setting:: ENGINE

ENGINE

~~~~~~

Default: ``''`` (Empty string)

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

    * ``'django.db.backends.postgresql_psycopg2'``

    * ``'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``). Writing a whole new database backend from

scratch is left as an exercise to the reader; see the other backends for

examples.

.. note::

    Prior to Django 1.2, you could use a short version of the backend name

    to reference the built-in database backends (e.g., you could use

    ``'sqlite3'`` to refer to the SQLite backend). This format has been

    deprecated, and will be removed in Django 1.4.

.. 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, an empty string means to use a Unix domain socket

for the connection, rather than a network connection to localhost. If you

explicitly need to use a TCP/IP connection on the local machine with

PostgreSQL, specify ``localhost`` here.

.. 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:: 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:: USER

USER

~~~~

Default: ``''`` (Empty string)

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

.. setting:: TEST_CHARSET

TEST_CHARSET

~~~~~~~~~~~~

Default: ``None``

The character set encoding used to create the test database. The value of this

string is passed directly through to the database, so its format is

backend-specific.

Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and

MySQL_ (``mysql``) backends.

.. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html

.. _MySQL: http://dev.mysql.com/doc/refman/5.0/en/charset-database.html

.. setting:: TEST_COLLATION

TEST_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

TEST_DEPENDENCIES

~~~~~~~~~~~~~~~~~

.. versionadded:: 1.2.4

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

TEST_MIRROR

~~~~~~~~~~~

Default: ``None``

The alias of the database that this database should mirror during

testing.

This setting exists to allow for testing of master/slave

configurations of multiple databases. See the documentation on

:ref:`testing master/slave configurations

<topics-testing-masterslave>` for details.

.. setting:: TEST_NAME

TEST_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 :doc:`/topics/testing`.

.. setting:: TEST_USER

TEST_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.

.. setting:: DATABASE_ROUTERS

DATABASE_ROUTERS

----------------

.. versionadded:: 1.2

Default: ``[]`` (Empty list)

The list of routers that will be used to determine which database

to use when performing a database queries.

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>`.

.. versionchanged:: 1.2

    This setting can now be overriden by setting ``USE_L10N`` to ``True``.

See also ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``SHORT_DATE_FORMAT``.

.. setting:: DATE_INPUT_FORMATS

DATE_INPUT_FORMATS

------------------

.. versionadded:: 1.2

Default::

    ('%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', '%b %d %Y',

    '%b %d, %Y', '%d %b %Y', '%d %b, %Y', '%B %d %Y',

    '%B %d, %Y', '%d %B %Y', '%d %B, %Y')

A tuple of formats that will be accepted when inputting data on a date

field. Formats will be tried in order, using the first valid.

Note that these format strings are specified in Python's datetime_ module

syntax, that is different from the one used by Django for formatting dates

to be displayed.

See also ``DATETIME_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``.

.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior

.. 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>`.

.. versionchanged:: 1.2

    This setting can now be overriden by setting ``USE_L10N`` to ``True``.

See also ``DATE_FORMAT``, ``TIME_FORMAT`` and ``SHORT_DATETIME_FORMAT``.

.. setting:: DATETIME_INPUT_FORMATS

DATETIME_INPUT_FORMATS

----------------------

.. versionadded:: 1.2

Default::

    ('%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d',

    '%m/%d/%Y %H:%M:%S', '%m/%d/%Y %H:%M', '%m/%d/%Y',

    '%m/%d/%y %H:%M:%S', '%m/%d/%y %H:%M', '%m/%d/%y')

A tuple of formats that will be accepted when inputting data on a datetime

field. Formats will be tried in order, using the first valid.

Note that these format strings are specified in Python's datetime_ module

syntax, that is different from the one used by Django for formatting dates

to be displayed.