5 A Django settings file contains all the configuration of your Django
6 installation. This document explains how settings work and which settings are
12 A settings file is just a Python module with module-level variables.
14 Here are a couple of example settings::
17 DEFAULT_FROM_EMAIL = 'webmaster@example.com'
18 TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')
20 Because a settings file is a Python module, the following apply:
22 * It doesn't allow for Python syntax errors.
23 * It can assign settings dynamically using normal Python syntax.
26 MY_SETTING = [str(i) for i in range(30)]
28 * It can import values from other settings files.
30 Designating the settings
31 ========================
33 When you use Django, you have to tell it which settings you're using. Do this
34 by using an environment variable, ``DJANGO_SETTINGS_MODULE``.
36 The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g.
37 ``mysite.settings``. Note that the settings module should be on the
38 Python `import search path`_.
40 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
42 The django-admin.py utility
43 ---------------------------
45 When using `django-admin.py`_, you can either set the environment variable
46 once, or explicitly pass in the settings module each time you run the utility.
48 Example (Unix Bash shell)::
50 export DJANGO_SETTINGS_MODULE=mysite.settings
51 django-admin.py runserver
53 Example (Windows shell)::
55 set DJANGO_SETTINGS_MODULE=mysite.settings
56 django-admin.py runserver
58 Use the ``--settings`` command-line argument to specify the settings manually::
60 django-admin.py runserver --settings=mysite.settings
62 .. _django-admin.py: ../django-admin/
64 On the server (mod_python)
65 --------------------------
67 In your live server environment, you'll need to tell Apache/mod_python which
68 settings file to use. Do that with ``SetEnv``::
71 SetHandler python-program
72 PythonHandler django.core.handlers.modpython
73 SetEnv DJANGO_SETTINGS_MODULE mysite.settings
76 Read the `Django mod_python documentation`_ for more information.
78 .. _Django mod_python documentation: ../modpython/
83 A Django settings file doesn't have to define any settings if it doesn't need
84 to. Each setting has a sensible default value. These defaults live in the file
85 ``django/conf/global_settings.py``.
87 Here's the algorithm Django uses in compiling settings:
89 * Load settings from ``global_settings.py``.
90 * Load settings from the specified settings file, overriding the global
91 settings as necessary.
93 Note that a settings file should *not* import from ``global_settings``, because
96 Seeing which settings you've changed
97 ------------------------------------
99 There's an easy way to view which of your settings deviate from the default
100 settings. The command ``python manage.py diffsettings`` displays differences
101 between the current settings file and Django's default settings.
103 For more, see the `diffsettings documentation`_.
105 .. _diffsettings documentation: ../django-admin/#diffsettings
107 Using settings in Python code
108 =============================
110 In your Django apps, use settings by importing the object
111 ``django.conf.settings``. Example::
113 from django.conf import settings
118 Note that ``django.conf.settings`` isn't a module -- it's an object. So
119 importing individual settings is not possible::
121 from django.conf.settings import DEBUG # This won't work.
123 Also note that your code should *not* import from either ``global_settings`` or
124 your own settings file. ``django.conf.settings`` abstracts the concepts of
125 default settings and site-specific settings; it presents a single interface.
126 It also decouples the code that uses settings from the location of your
129 Altering settings at runtime
130 ============================
132 You shouldn't alter settings in your applications at runtime. For example,
133 don't do this in a view::
135 from django.conf import settings
137 settings.DEBUG = True # Don't do this!
139 The only place you should assign to settings is in a settings file.
144 Because a settings file contains sensitive information, such as the database
145 password, you should make every attempt to limit access to it. For example,
146 change its file permissions so that only you and your Web server's user can
147 read it. This is especially important in a shared-hosting environment.
152 Here's a full list of all available settings, in alphabetical order, and their
155 ABSOLUTE_URL_OVERRIDES
156 ----------------------
158 Default: ``{}`` (Empty dictionary)
160 A dictionary mapping ``"app_label.model_name"`` strings to functions that take
161 a model object and return its URL. This is a way of overriding
162 ``get_absolute_url()`` methods on a per-installation basis. Example::
164 ABSOLUTE_URL_OVERRIDES = {
165 'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,
166 'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
169 Note that the model name used in this setting should be all lower-case, regardless
170 of the case of the actual model class name.
175 Default: ``()`` (Empty tuple)
177 Used for admin-site settings modules, this should be a tuple of settings
178 modules (in the format ``'foo.bar.baz'``) for which this site is an admin.
180 The admin site uses this in its automatically-introspected documentation of
181 models, views and template tags.
186 Default: ``'/media/'``
188 The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use
194 Default: ``()`` (Empty tuple)
196 A tuple that lists people who get code error notifications. When
197 ``DEBUG=False`` and a view raises an exception, Django will e-mail these people
198 with the full exception information. Each member of the tuple should be a tuple
199 of (Full name, e-mail address). Example::
201 (('John', 'john@example.com'), ('Mary', 'mary@example.com'))
203 Note that Django will e-mail *all* of these people whenever an error happens. See the
204 section on `error reporting via e-mail`_ for more information.
206 ALLOWED_INCLUDE_ROOTS
207 ---------------------
209 Default: ``()`` (Empty tuple)
211 A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template
212 tag. This is a security measure, so that template authors can't access files
213 that they shouldn't be accessing.
215 For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``,
216 then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}``
224 Whether to append trailing slashes to URLs. This is only used if
225 ``CommonMiddleware`` is installed (see the `middleware docs`_). See also
228 AUTHENTICATION_BACKENDS
229 -----------------------
231 Default: ``('django.contrib.auth.backends.ModelBackend',)``
233 A tuple of authentication backend classes (as strings) to use when
234 attempting to authenticate a user. See the `authentication backends
235 documentation`_ for details.
237 .. _authentication backends documentation: ../authentication/#other-authentication-sources
244 The site-specific user profile model used by this site. See the
245 `documentation on user profile models`_ for details.
247 .. _documentation on user profile models: ../authentication/#storing-additional-information-about-users
252 Default: ``'simple://'``
254 The cache backend to use. See the `cache docs`_.
256 CACHE_MIDDLEWARE_KEY_PREFIX
257 ---------------------------
259 Default: ``''`` (Empty string)
261 The cache key prefix that the cache middleware should use. See the
264 CACHE_MIDDLEWARE_SECONDS
265 ------------------------
269 The default number of seconds to cache a page when the caching middleware or
270 ``cache_page()`` decorator is used.
275 Default: ``''`` (Empty string)
277 The database backend to use. The build-in database backends are
278 ``'postgresql_psycopg2'``, ``'postgresql'``, ``'mysql'``, ``'mysql_old'``,
279 ``'sqlite3'``, ``'oracle'``, or ``'ado_mssql'``.
281 In the Django development version, you can use a database backend that doesn't
282 ship with Django by setting ``DATABASE_ENGINE`` to a fully-qualified path (i.e.
283 ``mypackage.backends.whatever``). Writing a whole new database backend from
284 scratch is left as an exercise to the reader; see the other backends for
290 Default: ``''`` (Empty string)
292 Which host to use when connecting to the database. An empty string means
293 localhost. Not used with SQLite.
295 If this value starts with a forward slash (``'/'``) and you're using MySQL,
296 MySQL will connect via a Unix socket to the specified socket. For example::
298 DATABASE_HOST = '/var/run/mysql'
300 If you're using MySQL and this value *doesn't* start with a forward slash, then
301 this value is assumed to be the host.
303 If you're using PostgreSQL, an empty string means to use a Unix domain socket
304 for the connection, rather than a network connection to localhost. If you
305 explictly need to use a TCP/IP connection on the local machine with
306 PostgreSQL, specify ``localhost`` here.
311 Default: ``''`` (Empty string)
313 The name of the database to use. For SQLite, it's the full path to the database
319 Default: ``{}`` (Empty dictionary)
321 Extra parameters to use when connecting to the database. Consult backend
322 module's document for available keywords.
327 Default: ``''`` (Empty string)
329 The password to use when connecting to the database. Not used with SQLite.
334 Default: ``''`` (Empty string)
336 The port to use when connecting to the database. An empty string means the
337 default port. Not used with SQLite.
342 Default: ``''`` (Empty string)
344 The username to use when connecting to the database. Not used with SQLite.
349 Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``)
351 The default formatting to use for date fields on Django admin change-list
352 pages -- and, possibly, by other parts of the system. See
353 `allowed date format strings`_.
355 See also ``DATETIME_FORMAT``, ``TIME_FORMAT``, ``YEAR_MONTH_FORMAT``
356 and ``MONTH_DAY_FORMAT``.
358 .. _allowed date format strings: ../templates/#now
363 Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``)
365 The default formatting to use for datetime fields on Django admin change-list
366 pages -- and, possibly, by other parts of the system. See
367 `allowed date format strings`_.
369 See also ``DATE_FORMAT``, ``DATETIME_FORMAT``, ``TIME_FORMAT``,
370 ``YEAR_MONTH_FORMAT`` and ``MONTH_DAY_FORMAT``.
372 .. _allowed date format strings: ../templates/#now
379 A boolean that turns on/off debug mode.
381 If you define custom settings, django/views/debug.py has a ``HIDDEN_SETTINGS``
382 regular expression which will hide from the DEBUG view anything that contains
383 ``'SECRET'``, ``'PASSWORD'``, or ``'PROFANITIES'``. This allows untrusted users to
384 be able to give backtraces without seeing sensitive (or offensive) settings.
386 Still, note that there are always going to be sections of your debug output that
387 are inappropriate for public consumption. File paths, configuration options, and
388 the like all give attackers extra information about your server. Never deploy a
389 site with ``DEBUG`` turned on.
396 Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't
397 manually specified. Used with ``DEFAULT_CONTENT_TYPE`` to construct the
398 ``Content-Type`` header.
403 Default: ``'text/html'``
405 Default content type to use for all ``HttpResponse`` objects, if a MIME type
406 isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the
407 ``Content-Type`` header.
412 Default: ``'webmaster@localhost'``
414 Default e-mail address to use for various automated correspondence from the
420 **New in Django development version**
422 Default: ``''`` (Empty string)
424 Default tablespace to use for models that don't specify one, if the
427 DEFAULT_INDEX_TABLESPACE
428 ------------------------
430 **New in Django development version**
432 Default: ``''`` (Empty string)
434 Default tablespace to use for indexes on fields that don't specify
435 one, if the backend supports it.
437 DISALLOWED_USER_AGENTS
438 ----------------------
440 Default: ``()`` (Empty tuple)
442 List of compiled regular expression objects representing User-Agent strings
443 that are not allowed to visit any page, systemwide. Use this for bad
444 robots/crawlers. This is only used if ``CommonMiddleware`` is installed (see
445 the `middleware docs`_).
450 Default: ``'localhost'``
452 The host to use for sending e-mail.
454 See also ``EMAIL_PORT``.
459 Default: ``''`` (Empty string)
461 Password to use for the SMTP server defined in ``EMAIL_HOST``. This setting is
462 used in conjunction with ``EMAIL_HOST_USER`` when authenticating to the SMTP
463 server. If either of these settings is empty, Django won't attempt
466 See also ``EMAIL_HOST_USER``.
471 Default: ``''`` (Empty string)
473 Username to use for the SMTP server defined in ``EMAIL_HOST``. If empty,
474 Django won't attempt authentication.
476 See also ``EMAIL_HOST_PASSWORD``.
483 Port to use for the SMTP server defined in ``EMAIL_HOST``.
488 Default: ``'[Django] '``
490 Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins``
491 or ``django.core.mail.mail_managers``. You'll probably want to include the
497 **New in Django development version**
501 Whether to use a TLS (secure) connection when talking to the SMTP server.
506 **New in Django development version**
510 The character encoding used to decode any files read from disk. This includes
511 template files and initial SQL data files.
516 Default: ``()`` (Empty tuple)
518 List of locations of the fixture data files, in search order. Note that
519 these paths should use Unix-style forward slashes, even on Windows. See
520 `Testing Django Applications`_.
522 .. _Testing Django Applications: ../testing/
527 Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')``
529 See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``.
534 Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')``
536 A tuple of strings that specify beginnings of URLs that should be ignored by
537 the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and
538 the section on `error reporting via e-mail`_.
543 Default: ``()`` (Empty tuple)
545 A tuple of strings designating all applications that are enabled in this Django
546 installation. Each string should be a full Python path to a Python package that
547 contains a Django application, as created by `django-admin.py startapp`_.
549 .. _django-admin.py startapp: ../django-admin/#startapp-appname
554 Default: ``()`` (Empty tuple)
556 A tuple of IP addresses, as strings, that:
558 * See debug comments, when ``DEBUG`` is ``True``
559 * Receive X headers if the ``XViewMiddleware`` is installed (see the
565 Default: ``'/usr/bin/jing'``
567 Path to the "Jing" executable. Jing is a RELAX NG validator, and Django uses it
568 to validate each ``XMLField`` in your models.
569 See http://www.thaiopensource.com/relaxng/jing.html .
576 A string representing the language code for this installation. This should be
577 in standard language format. For example, U.S. English is ``"en-us"``. See the
578 `internationalization docs`_.
580 .. _internationalization docs: ../i18n/
585 Default: ``'django_language'``
587 The name of the cookie to use for the language cookie. This can be whatever
588 you want (but should be different from SESSION_COOKIE_NAME). See the
589 `internationalization docs`_ for details.
595 Default: A tuple of all available languages. This list is continually growing
596 and including a copy here would inevitably become rapidly out of date. You can
597 see the current list of translated languages by looking in
598 ``django/conf/global_settings.py`` (or view the `online source`_).
600 .. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py
602 The list is a tuple of two-tuples in the format (language code, language
603 name) -- for example, ``('ja', 'Japanese')``. This specifies which languages
604 are available for language selection. See the `internationalization docs`_ for
607 Generally, the default value should suffice. Only set this setting if you want
608 to restrict language selection to a subset of the Django-provided languages.
610 If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as
611 translation strings (as in the default value displayed above) -- but use a
612 "dummy" ``gettext()`` function, not the one in ``django.utils.translation``.
613 You should *never* import ``django.utils.translation`` from within your
614 settings file, because that module in itself depends on the settings, and that
615 would cause a circular import.
617 The solution is to use a "dummy" ``gettext()`` function. Here's a sample
620 gettext = lambda s: s
623 ('de', gettext('German')),
624 ('en', gettext('English')),
627 With this arrangement, ``make-messages.py`` will still find and mark these
628 strings for translation, but the translation won't happen at runtime -- so
629 you'll have to remember to wrap the languages in the *real* ``gettext()`` in
630 any code that uses ``LANGUAGES`` at runtime.
635 Default: ``()`` (Empty tuple)
637 A tuple of directories where Django looks for translation files.
638 See the `internationalization docs section`_ explaining the variable and the
641 .. _internationalization docs section: ../i18n/#using-translations-in-your-own-projects
646 **New in Django development version**
648 Default: ``'/accounts/profile/'``
650 The URL where requests are redirected after login when the
651 ``contrib.auth.login`` view gets no ``next`` parameter.
653 This is used by the `@login_required`_ decorator, for example.
658 **New in Django development version**
660 Default: ``'/accounts/login/'``
662 The URL where requests are redirected for login, specially when using the
663 `@login_required`_ decorator.
668 **New in Django development version**
670 Default: ``'/accounts/logout/'``
672 LOGIN_URL counterpart.
677 Default: ``()`` (Empty tuple)
679 A tuple in the same format as ``ADMINS`` that specifies who should get
680 broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``.
685 Default: ``''`` (Empty string)
687 Absolute path to the directory that holds media for this installation.
688 Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``.
693 Default: ``''`` (Empty string)
695 URL that handles the media served from ``MEDIA_ROOT``.
696 Example: ``"http://media.lawrence.com"``
698 Note that this should have a trailing slash if it has a path component.
700 Good: ``"http://www.example.com/static/"``
701 Bad: ``"http://www.example.com/static"``
708 ("django.contrib.sessions.middleware.SessionMiddleware",
709 "django.contrib.auth.middleware.AuthenticationMiddleware",
710 "django.middleware.common.CommonMiddleware",
711 "django.middleware.doc.XViewMiddleware")
713 A tuple of middleware classes to use. See the `middleware docs`_.
720 The default formatting to use for date fields on Django admin change-list
721 pages -- and, possibly, by other parts of the system -- in cases when only the
722 month and day are displayed.
724 For example, when a Django admin change-list page is being filtered by a date
725 drilldown, the header for a given day displays the day and month. Different
726 locales have different formats. For example, U.S. English would say
727 "January 1," whereas Spanish might say "1 Enero."
729 See `allowed date format strings`_. See also ``DATE_FORMAT``,
730 ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``YEAR_MONTH_FORMAT``.
737 Whether to prepend the "www." subdomain to URLs that don't have it. This is
738 only used if ``CommonMiddleware`` is installed (see the `middleware docs`_).
739 See also ``APPEND_SLASH``.
744 A tuple of profanities, as strings, that will trigger a validation error when
745 the ``hasNoProfanities`` validator is called.
747 We don't list the default values here, because that would be profane. To see
748 the default values, see the file ``django/conf/global_settings.py``.
755 A string representing the full Python import path to your root URLconf. For example:
756 ``"mydjangoapps.urls"``. See `How Django processes a request`_.
758 .. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
763 Default: ``''`` (Empty string)
765 A secret key for this particular Django installation. Used to provide a seed in
766 secret-key hashing algorithms. Set this to a random string -- the longer, the
767 better. ``django-admin.py startproject`` creates one automatically.
769 SEND_BROKEN_LINK_EMAILS
770 -----------------------
774 Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a
775 Django-powered page that is 404ed with a non-empty referer (i.e., a broken
776 link). This is only used if ``CommonMiddleware`` is installed (see the
777 `middleware docs`_). See also ``IGNORABLE_404_STARTS``,
778 ``IGNORABLE_404_ENDS`` and the section on `error reporting via e-mail`_
780 SERIALIZATION_MODULES
781 ---------------------
783 Default: Not defined.
785 A dictionary of modules containing serializer definitions (provided as
786 strings), keyed by a string identifier for that serialization type. For
787 example, to define a YAML serializer, use::
789 SERIALIZATION_MODULES = { 'yaml' : 'path.to.yaml_serializer' }
794 Default: ``'root@localhost'``
796 The e-mail address that error messages come from, such as those sent to
797 ``ADMINS`` and ``MANAGERS``.
802 **New in Django development version**
804 Default: ``django.contrib.sessions.backends.db``
806 Controls where Django stores session data. Valid values are:
808 * ``'django.contrib.sessions.backends.db'``
809 * ``'django.contrib.sessions.backends.file'``
810 * ``'django.contrib.sessions.backends.cache'``
812 See the `session docs`_ for more details.
817 Default: ``1209600`` (2 weeks, in seconds)
819 The age of session cookies, in seconds. See the `session docs`_.
821 SESSION_COOKIE_DOMAIN
822 ---------------------
826 The domain to use for session cookies. Set this to a string such as
827 ``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard
828 domain cookie. See the `session docs`_.
833 Default: ``'sessionid'``
835 The name of the cookie to use for sessions. This can be whatever you want (but
836 should be different from ``LANGUAGE_COOKIE_NAME``). See the `session docs`_.
841 **New in Django development version**
845 The path set on the session cookie. This should either match the URL path of your
846 Django installation or be parent of that path.
848 This is useful if you have multiple Django instances running under the same
849 hostname. They can use different cookie paths, and each instance will only see
850 its own session cookie.
852 SESSION_COOKIE_SECURE
853 ---------------------
857 Whether to use a secure cookie for the session cookie. If this is set to
858 ``True``, the cookie will be marked as "secure," which means browsers may
859 ensure that the cookie is only sent under an HTTPS connection.
860 See the `session docs`_.
862 SESSION_EXPIRE_AT_BROWSER_CLOSE
863 -------------------------------
867 Whether to expire the session when the user closes his or her browser.
868 See the `session docs`_.
873 **New in Django development version**
877 If you're using file-based session storage, this sets the directory in
878 which Django will store session data. See the `session docs`_ for
881 SESSION_SAVE_EVERY_REQUEST
882 --------------------------
886 Whether to save the session data on every request. See the `session docs`_.
893 The ID, as an integer, of the current site in the ``django_site`` database
894 table. This is used so that application data can hook into specific site(s)
895 and a single database can manage content for multiple sites.
897 See the `site framework docs`_.
899 .. _site framework docs: ../sites/
901 TEMPLATE_CONTEXT_PROCESSORS
902 ---------------------------
906 ("django.core.context_processors.auth",
907 "django.core.context_processors.debug",
908 "django.core.context_processors.i18n",
909 "django.core.context_processors.media")
911 A tuple of callables that are used to populate the context in ``RequestContext``.
912 These callables take a request object as their argument and return a dictionary
913 of items to be merged into the context.
920 A boolean that turns on/off template debug mode. If this is ``True``, the fancy
921 error page will display a detailed report for any ``TemplateSyntaxError``. This
922 report contains the relevant snippet of the template, with the appropriate line
925 Note that Django only displays fancy error pages if ``DEBUG`` is ``True``, so
926 you'll want to set that to take advantage of this setting.
933 Default: ``()`` (Empty tuple)
935 List of locations of the template source files, in search order. Note that
936 these paths should use Unix-style forward slashes, even on Windows.
938 See the `template documentation`_.
943 Default: ``('django.template.loaders.filesystem.load_template_source',)``
945 A tuple of callables (as strings) that know how to import templates from
946 various sources. See the `template documentation`_.
948 TEMPLATE_STRING_IF_INVALID
949 --------------------------
951 Default: ``''`` (Empty string)
953 Output, as a string, that the template system should use for invalid (e.g.
954 misspelled) variables. See `How invalid variables are handled`_.
956 .. _How invalid variables are handled: ../templates_python/#how-invalid-variables-are-handled
958 TEST_DATABASE_CHARSET
959 ---------------------
961 **New in Django development version**
965 The character set encoding used to create the test database. The value of this
966 string is passed directly through to the database, so its format is
969 Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and MySQL_ (``mysql``, ``mysql_old``) backends.
971 .. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html
972 .. _MySQL: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
974 TEST_DATABASE_COLLATION
975 ------------------------
977 **New in Django development version**
981 The collation order to use when creating the test database. This value is
982 passed directly to the backend, so its format is backend-specific.
984 Only supported for ``mysql`` and ``mysql_old`` backends (see `section 10.3.2`_
985 of the MySQL manual for details).
987 .. _section 10.3.2: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
994 The name of database to use when running the test suite.
996 If the default value (``None``) is used with the SQLite database engine, the
997 tests will use a memory resident database. For all other database engines the
998 test database will use the name ``'test_' + settings.DATABASE_NAME``.
1000 See `Testing Django Applications`_.
1002 .. _Testing Django Applications: ../testing/
1007 Default: ``'django.test.simple.run_tests'``
1009 The name of the method to use for starting the test suite. See
1010 `Testing Django Applications`_.
1012 .. _Testing Django Applications: ../testing/
1017 Default: ``'P'`` (e.g. ``4 p.m.``)
1019 The default formatting to use for time fields on Django admin change-list
1020 pages -- and, possibly, by other parts of the system. See
1021 `allowed date format strings`_.
1023 See also ``DATE_FORMAT``, ``DATETIME_FORMAT``, ``TIME_FORMAT``,
1024 ``YEAR_MONTH_FORMAT`` and ``MONTH_DAY_FORMAT``.
1026 .. _allowed date format strings: ../templates/#now
1031 Default: ``'America/Chicago'``
1033 A string representing the time zone for this installation. `See available choices`_.
1034 (Note that list of available choices lists more than one on the same line;
1035 you'll want to use just one of the choices for a given time zone. For instance,
1036 one line says ``'Europe/London GB GB-Eire'``, but you should use the first bit
1037 of that -- ``'Europe/London'`` -- as your ``TIME_ZONE`` setting.)
1039 Note that this is the time zone to which Django will convert all dates/times --
1040 not necessarily the timezone of the server. For example, one server may serve
1041 multiple Django-powered sites, each with a separate time-zone setting.
1043 Normally, Django sets the ``os.environ['TZ']`` variable to the time zone you
1044 specify in the ``TIME_ZONE`` setting. Thus, all your views and models will
1045 automatically operate in the correct time zone. However, if you're using the
1046 manual configuration option (see below), Django will *not* touch the ``TZ``
1047 environment variable, and it'll be up to you to ensure your processes are
1048 running in the correct environment.
1051 Django cannot reliably use alternate time zones in a Windows environment.
1052 If you're running Django on Windows, this variable must be set to match the
1055 URL_VALIDATOR_USER_AGENT
1056 ------------------------
1058 Default: ``Django/<version> (http://www.djangoproject.com/)``
1060 The string to use as the ``User-Agent`` header when checking to see if URLs
1061 exist (see the ``verify_exists`` option on URLField_).
1063 .. _URLField: ../model-api/#urlfield
1070 A boolean that specifies whether to output the "Etag" header. This saves
1071 bandwidth but slows down performance. This is only used if ``CommonMiddleware``
1072 is installed (see the `middleware docs`_).
1079 A boolean that specifies whether Django's internationalization system should be
1080 enabled. This provides an easy way to turn it off, for performance. If this is
1081 set to ``False``, Django will make some optimizations so as not to load the
1082 internationalization machinery.
1089 The default formatting to use for date fields on Django admin change-list
1090 pages -- and, possibly, by other parts of the system -- in cases when only the
1091 year and month are displayed.
1093 For example, when a Django admin change-list page is being filtered by a date
1094 drilldown, the header for a given month displays the month and the year.
1095 Different locales have different formats. For example, U.S. English would say
1096 "January 2006," whereas another locale might say "2006/January."
1098 See `allowed date format strings`_. See also ``DATE_FORMAT``,
1099 ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``MONTH_DAY_FORMAT``.
1101 .. _cache docs: ../cache/
1102 .. _middleware docs: ../middleware/
1103 .. _session docs: ../sessions/
1104 .. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
1105 .. _template documentation: ../templates_python/
1107 Creating your own settings
1108 ==========================
1110 There's nothing stopping you from creating your own settings, for your own
1111 Django apps. Just follow these conventions:
1113 * Setting names are in all uppercase.
1114 * For settings that are sequences, use tuples instead of lists. This is
1115 purely for performance.
1116 * Don't reinvent an already-existing setting.
1118 Using settings without setting DJANGO_SETTINGS_MODULE
1119 =====================================================
1121 In some cases, you might want to bypass the ``DJANGO_SETTINGS_MODULE``
1122 environment variable. For example, if you're using the template system by
1123 itself, you likely don't want to have to set up an environment variable
1124 pointing to a settings module.
1126 In these cases, you can configure Django's settings manually. Do this by
1127 calling ``django.conf.settings.configure()``.
1131 from django.conf import settings
1133 settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,
1134 TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))
1136 Pass ``configure()`` as many keyword arguments as you'd like, with each keyword
1137 argument representing a setting and its value. Each argument name should be all
1138 uppercase, with the same name as the settings described above. If a particular
1139 setting is not passed to ``configure()`` and is needed at some later point,
1140 Django will use the default setting value.
1142 Configuring Django in this fashion is mostly necessary -- and, indeed,
1143 recommended -- when you're using a piece of the framework inside a larger
1146 Consequently, when configured via ``settings.configure()``, Django will not
1147 make any modifications to the process environment variables. (See the
1148 explanation of ``TIME_ZONE``, above, for why this would normally occur.) It's
1149 assumed that you're already in full control of your environment in these cases.
1151 Custom default settings
1152 -----------------------
1154 If you'd like default values to come from somewhere other than
1155 ``django.conf.global_settings``, you can pass in a module or class that
1156 provides the default settings as the ``default_settings`` argument (or as the
1157 first positional argument) in the call to ``configure()``.
1159 In this example, default settings are taken from ``myapp_defaults``, and the
1160 ``DEBUG`` setting is set to ``True``, regardless of its value in
1161 ``myapp_defaults``::
1163 from django.conf import settings
1164 from myapp import myapp_defaults
1166 settings.configure(default_settings=myapp_defaults, DEBUG=True)
1168 The following example, which uses ``myapp_defaults`` as a positional argument,
1171 settings.configure(myapp_defaults, DEBUG = True)
1173 Normally, you will not need to override the defaults in this fashion. The
1174 Django defaults are sufficiently tame that you can safely use them. Be aware
1175 that if you do pass in a new default module, it entirely *replaces* the Django
1176 defaults, so you must specify a value for every possible setting that might be
1177 used in that code you are importing. Check in
1178 ``django.conf.settings.global_settings`` for the full list.
1180 Either configure() or DJANGO_SETTINGS_MODULE is required
1181 --------------------------------------------------------
1183 If you're not setting the ``DJANGO_SETTINGS_MODULE`` environment variable, you
1184 *must* call ``configure()`` at some point before using any code that reads
1187 If you don't set ``DJANGO_SETTINGS_MODULE`` and don't call ``configure()``,
1188 Django will raise an ``ImportError`` exception the first time a setting
1191 If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then*
1192 call ``configure()``, Django will raise a ``RuntimeError`` indicating
1193 that settings have already been configured.
1195 Also, it's an error to call ``configure()`` more than once, or to call
1196 ``configure()`` after any setting has been accessed.
1198 It boils down to this: Use exactly one of either ``configure()`` or
1199 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
1201 .. _@login_required: ../authentication/#the-login-required-decorator
1203 Error reporting via e-mail
1204 ==========================
1209 When ``DEBUG`` is ``False``, Django will e-mail the users listed in the
1210 ``ADMIN`` setting whenever your code raises an unhandled exception and results
1211 in an internal server error (HTTP status code 500). This gives the
1212 administrators immediate notification of any errors.
1214 To disable this behavior, just remove all entries from the ``ADMINS`` setting.
1219 When ``DEBUG`` is ``False``, ``SEND_BROKEN_LINK_EMAILS`` is ``True`` and your
1220 ``MIDDLEWARE_CLASSES`` setting includes ``CommonMiddleware``, Django will
1221 e-mail the users listed in the ``MANAGERS`` setting whenever your code raises
1222 a 404 and the request has a referer. (It doesn't bother to e-mail for 404s
1223 that don't have a referer.)
1225 You can tell Django to stop reporting particular 404s by tweaking the
1226 ``IGNORABLE_404_ENDS`` and ``IGNORABLE_404_STARTS`` settings. Both should be a
1227 tuple of strings. For example::
1229 IGNORABLE_404_ENDS = ('.php', '.cgi')
1230 IGNORABLE_404_STARTS = ('/phpmyadmin/',)
1232 In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not*
1233 be reported. Neither will any URL starting with ``/phpmyadmin/``.
1235 To disable this behavior, just remove all entries from the ``MANAGERS`` setting.