Correct an example in docs/modelforms.txt, and fix some reST formatting
[django.git] / docs / settings.txt
blobace893f1b578aff0032a25a105b0e63f64fe6368
1 ===============
2 Django settings
3 ===============
5 A Django settings file contains all the configuration of your Django
6 installation. This document explains how settings work and which settings are
7 available.
9 The basics
10 ==========
12 A settings file is just a Python module with module-level variables.
14 Here are a couple of example settings::
16     DEBUG = False
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.
24       For example::
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``::
70     <Location "/mysite/">
71         SetHandler python-program
72         PythonHandler django.core.handlers.modpython
73         SetEnv DJANGO_SETTINGS_MODULE mysite.settings
74     </Location>
76 Read the `Django mod_python documentation`_ for more information.
78 .. _Django mod_python documentation: ../modpython/
80 Default settings
81 ================
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
94 that's redundant.
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
115     if settings.DEBUG:
116         # Do something
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
127 settings.
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.
141 Security
142 ========
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.
149 Available settings
150 ==================
152 Here's a full list of all available settings, in alphabetical order, and their
153 default values.
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),
167     }
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.
172 ADMIN_FOR
173 ---------
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.
183 ADMIN_MEDIA_PREFIX
184 ------------------
186 Default: ``'/media/'``
188 The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use
189 a trailing slash.
191 ADMINS
192 ------
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 %}``
217 wouldn't.
219 APPEND_SLASH
220 ------------
222 Default: ``True``
224 Whether to append trailing slashes to URLs. This is only used if
225 ``CommonMiddleware`` is installed (see the `middleware docs`_). See also
226 ``PREPEND_WWW``.
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
239 AUTH_PROFILE_MODULE
240 -------------------
242 Default: Not defined
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
249 CACHE_BACKEND
250 -------------
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
262 `cache docs`_.
264 CACHE_MIDDLEWARE_SECONDS
265 ------------------------
267 Default: ``600``
269 The default number of seconds to cache a page when the caching middleware or
270 ``cache_page()`` decorator is used.
272 DATABASE_ENGINE
273 ---------------
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
285 examples.
287 DATABASE_HOST
288 -------------
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.
308 DATABASE_NAME
309 -------------
311 Default: ``''`` (Empty string)
313 The name of the database to use. For SQLite, it's the full path to the database
314 file.
316 DATABASE_OPTIONS
317 ----------------
319 Default: ``{}`` (Empty dictionary)
321 Extra parameters to use when connecting to the database. Consult backend
322 module's document for available keywords.
324 DATABASE_PASSWORD
325 -----------------
327 Default: ``''`` (Empty string)
329 The password to use when connecting to the database. Not used with SQLite.
331 DATABASE_PORT
332 -------------
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.
339 DATABASE_USER
340 -------------
342 Default: ``''`` (Empty string)
344 The username to use when connecting to the database. Not used with SQLite.
346 DATE_FORMAT
347 -----------
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
360 DATETIME_FORMAT
361 ---------------
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
374 DEBUG
375 -----
377 Default: ``False``
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.
391 DEFAULT_CHARSET
392 ---------------
394 Default: ``'utf-8'``
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.
400 DEFAULT_CONTENT_TYPE
401 --------------------
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.
409 DEFAULT_FROM_EMAIL
410 ------------------
412 Default: ``'webmaster@localhost'``
414 Default e-mail address to use for various automated correspondence from the
415 site manager(s).
417 DEFAULT_TABLESPACE
418 ------------------
420 **New in Django development version**
422 Default: ``''`` (Empty string)
424 Default tablespace to use for models that don't specify one, if the
425 backend supports it.
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`_).
447 EMAIL_HOST
448 ----------
450 Default: ``'localhost'``
452 The host to use for sending e-mail.
454 See also ``EMAIL_PORT``.
456 EMAIL_HOST_PASSWORD
457 -------------------
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
464 authenticaion.
466 See also ``EMAIL_HOST_USER``.
468 EMAIL_HOST_USER
469 ---------------
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``.
478 EMAIL_PORT
479 ----------
481 Default: ``25``
483 Port to use for the SMTP server defined in ``EMAIL_HOST``.
485 EMAIL_SUBJECT_PREFIX
486 --------------------
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
492 trailing space.
494 EMAIL_USE_TLS
495 -------------
497 **New in Django development version**
499 Default: ``False``
501 Whether to use a TLS (secure) connection when talking to the SMTP server.
503 FILE_CHARSET
504 ------------
506 **New in Django development version**
508 Default: ``'utf-8'``
510 The character encoding used to decode any files read from disk. This includes
511 template files and initial SQL data files.
513 FIXTURE_DIRS
514 -------------
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/
524 IGNORABLE_404_ENDS
525 ------------------
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``.
531 IGNORABLE_404_STARTS
532 --------------------
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`_.
540 INSTALLED_APPS
541 --------------
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
551 INTERNAL_IPS
552 ------------
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
560       `middleware docs`_)
562 JING_PATH
563 ---------
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 .
571 LANGUAGE_CODE
572 -------------
574 Default: ``'en-us'``
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/
582 LANGUAGE_COOKIE_NAME
583 --------------------
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.
592 LANGUAGES
593 ---------
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
605 details.
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
618 settings file::
620     gettext = lambda s: s
622     LANGUAGES = (
623         ('de', gettext('German')),
624         ('en', gettext('English')),
625     )
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.
632 LOCALE_PATHS
633 ------------
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
639 default behavior.
641 .. _internationalization docs section: ../i18n/#using-translations-in-your-own-projects
643 LOGIN_REDIRECT_URL
644 ------------------
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.
655 LOGIN_URL
656 ---------
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.
665 LOGOUT_URL
666 ----------
668 **New in Django development version**
670 Default: ``'/accounts/logout/'``
672 LOGIN_URL counterpart.
674 MANAGERS
675 --------
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``.
682 MEDIA_ROOT
683 ----------
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``.
690 MEDIA_URL
691 ---------
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"``
703 MIDDLEWARE_CLASSES
704 ------------------
706 Default::
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`_.
715 MONTH_DAY_FORMAT
716 ----------------
718 Default: ``'F j'``
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``.
732 PREPEND_WWW
733 -----------
735 Default: ``False``
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``.
741 PROFANITIES_LIST
742 ----------------
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``.
750 ROOT_URLCONF
751 ------------
753 Default: Not defined
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
760 SECRET_KEY
761 ----------
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 -----------------------
772 Default: ``False``
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' }
791 SERVER_EMAIL
792 ------------
794 Default: ``'root@localhost'``
796 The e-mail address that error messages come from, such as those sent to
797 ``ADMINS`` and ``MANAGERS``.
799 SESSION_ENGINE
800 --------------
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.
814 SESSION_COOKIE_AGE
815 ------------------
817 Default: ``1209600`` (2 weeks, in seconds)
819 The age of session cookies, in seconds. See the `session docs`_.
821 SESSION_COOKIE_DOMAIN
822 ---------------------
824 Default: ``None``
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`_.
830 SESSION_COOKIE_NAME
831 -------------------
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`_.
838 SESSION_COOKIE_PATH
839 -------------------
841 **New in Django development version**
843 Default: ``'/'``
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 ---------------------
855 Default: ``False``
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 -------------------------------
865 Default: ``False``
867 Whether to expire the session when the user closes his or her browser.
868 See the `session docs`_.
870 SESSION_FILE_PATH
871 -----------------
873 **New in Django development version**
875 Default: ``/tmp/``
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
879 more details.
881 SESSION_SAVE_EVERY_REQUEST
882 --------------------------
884 Default: ``False``
886 Whether to save the session data on every request. See the `session docs`_.
888 SITE_ID
889 -------
891 Default: Not defined
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 ---------------------------
904 Default::
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.
915 TEMPLATE_DEBUG
916 --------------
918 Default: ``False``
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
923 highlighted.
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.
928 See also ``DEBUG``.
930 TEMPLATE_DIRS
931 -------------
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`_.
940 TEMPLATE_LOADERS
941 ----------------
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**
963 Default: ``None``
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
967 backend-specific.
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**
979 Default: ``None``
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
989 TEST_DATABASE_NAME
990 ------------------
992 Default: ``None``
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/
1004 TEST_RUNNER
1005 -----------
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/
1014 TIME_FORMAT
1015 -----------
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
1028 TIME_ZONE
1029 ---------
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.
1050 .. note::
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
1053     system timezone.
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
1065 USE_ETAGS
1066 ---------
1068 Default: ``False``
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`_).
1074 USE_I18N
1075 --------
1077 Default: ``True``
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.
1084 YEAR_MONTH_FORMAT
1085 -----------------
1087 Default: ``'F Y'``
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()``.
1129 Example::
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
1144 application.
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,
1169 is equivalent::
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
1185 settings.
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
1189 is accessed.
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 ==========================
1206 Server errors
1207 -------------
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.
1216 404 errors
1217 ----------
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.