docs/settings.txt

   1 ===============
   2 Django settings
   3 ===============
   4
   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.
   8
   9 The basics
  10 ==========
  11
  12 A settings file is just a Python module with module-level variables.
  13
  14 Here are a couple of example settings::
  15
  16     DEBUG = False
  17     DEFAULT_FROM_EMAIL = 'webmaster@example.com'
  18     TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')
  19
  20 Because a settings file is a Python module, the following apply:
  21
  22     * It doesn't allow for Python syntax errors.
  23     * It can assign settings dynamically using normal Python syntax.
  24       For example::
  25
  26           MY_SETTING = [str(i) for i in range(30)]
  27
  28     * It can import values from other settings files.
  29
  30 Designating the settings
  31 ========================
  32
  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``.
  35
  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`_.
  39
  40 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
  41
  42 The django-admin.py utility
  43 ---------------------------
  44
  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.
  47
  48 Example (Unix Bash shell)::
  49
  50     export DJANGO_SETTINGS_MODULE=mysite.settings
  51     django-admin.py runserver
  52
  53 Example (Windows shell)::
  54
  55     set DJANGO_SETTINGS_MODULE=mysite.settings
  56     django-admin.py runserver
  57
  58 Use the ``--settings`` command-line argument to specify the settings manually::
  59
  60     django-admin.py runserver --settings=mysite.settings
  61
  62 .. _django-admin.py: ../django-admin/
  63
  64 On the server (mod_python)
  65 --------------------------
  66
  67 In your live server environment, you'll need to tell Apache/mod_python which
  68 settings file to use. Do that with ``SetEnv``::
  69
  70     <Location "/mysite/">
  71         SetHandler python-program
  72         PythonHandler django.core.handlers.modpython
  73         SetEnv DJANGO_SETTINGS_MODULE mysite.settings
  74     </Location>
  75
  76 Read the `Django mod_python documentation`_ for more information.
  77
  78 .. _Django mod_python documentation: ../modpython/
  79
  80 Default settings
  81 ================
  82
  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``.
  86
  87 Here's the algorithm Django uses in compiling settings:
  88
  89     * Load settings from ``global_settings.py``.
  90     * Load settings from the specified settings file, overriding the global
  91       settings as necessary.
  92
  93 Note that a settings file should *not* import from ``global_settings``, because
  94 that's redundant.
  95
  96 Seeing which settings you've changed
  97 ------------------------------------
  98
  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.
 102
 103 For more, see the `diffsettings documentation`_.
 104
 105 .. _diffsettings documentation: ../django-admin/#diffsettings
 106
 107 Using settings in Python code
 108 =============================
 109
 110 In your Django apps, use settings by importing the object
 111 ``django.conf.settings``. Example::
 112
 113     from django.conf import settings
 114
 115     if settings.DEBUG:
 116         # Do something
 117
 118 Note that ``django.conf.settings`` isn't a module -- it's an object. So
 119 importing individual settings is not possible::
 120
 121     from django.conf.settings import DEBUG  # This won't work.
 122
 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.
 128
 129 Altering settings at runtime
 130 ============================
 131
 132 You shouldn't alter settings in your applications at runtime. For example,
 133 don't do this in a view::
 134
 135     from django.conf import settings
 136
 137     settings.DEBUG = True   # Don't do this!
 138
 139 The only place you should assign to settings is in a settings file.
 140
 141 Security
 142 ========
 143
 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.
 148
 149 Available settings
 150 ==================
 151
 152 Here's a full list of all available settings, in alphabetical order, and their
 153 default values.
 154
 155 ABSOLUTE_URL_OVERRIDES
 156 ----------------------
 157
 158 Default: ``{}`` (Empty dictionary)
 159
 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::
 163
 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     }
 168
 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.
 171
 172 ADMIN_FOR
 173 ---------
 174
 175 Default: ``()`` (Empty tuple)
 176
 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.
 179
 180 The admin site uses this in its automatically-introspected documentation of
 181 models, views and template tags.
 182
 183 ADMIN_MEDIA_PREFIX
 184 ------------------
 185
 186 Default: ``'/media/'``
 187
 188 The URL prefix for admin media -- CSS, JavaScript and images used by
 189 the Django administrative interface. Make sure to use a trailing
 190 slash, and to have this be different from the ``MEDIA_URL`` setting
 191 (since the same URL cannot be mapped onto two different sets of
 192 files).
 193
 194 ADMINS
 195 ------
 196
 197 Default: ``()`` (Empty tuple)
 198
 199 A tuple that lists people who get code error notifications. When
 200 ``DEBUG=False`` and a view raises an exception, Django will e-mail these people
 201 with the full exception information. Each member of the tuple should be a tuple
 202 of (Full name, e-mail address). Example::
 203
 204     (('John', 'john@example.com'), ('Mary', 'mary@example.com'))
 205
 206 Note that Django will e-mail *all* of these people whenever an error happens. See the
 207 section on `error reporting via e-mail`_ for more information.
 208
 209 ALLOWED_INCLUDE_ROOTS
 210 ---------------------
 211
 212 Default: ``()`` (Empty tuple)
 213
 214 A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template
 215 tag. This is a security measure, so that template authors can't access files
 216 that they shouldn't be accessing.
 217
 218 For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``,
 219 then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}``
 220 wouldn't.
 221
 222 APPEND_SLASH
 223 ------------
 224
 225 Default: ``True``
 226
 227 Whether to append trailing slashes to URLs. This is only used if
 228 ``CommonMiddleware`` is installed (see the `middleware docs`_). See also
 229 ``PREPEND_WWW``.
 230
 231 AUTHENTICATION_BACKENDS
 232 -----------------------
 233
 234 Default: ``('django.contrib.auth.backends.ModelBackend',)``
 235
 236 A tuple of authentication backend classes (as strings) to use when
 237 attempting to authenticate a user. See the `authentication backends
 238 documentation`_ for details.
 239
 240 .. _authentication backends documentation: ../authentication/#other-authentication-sources
 241
 242 AUTH_PROFILE_MODULE
 243 -------------------
 244
 245 Default: Not defined
 246
 247 The site-specific user profile model used by this site. See the
 248 `documentation on user profile models`_ for details.
 249
 250 .. _documentation on user profile models: ../authentication/#storing-additional-information-about-users
 251
 252 CACHE_BACKEND
 253 -------------
 254
 255 Default: ``'locmem://'``
 256
 257 The cache backend to use. See the `cache docs`_.
 258
 259 CACHE_MIDDLEWARE_KEY_PREFIX
 260 ---------------------------
 261
 262 Default: ``''`` (Empty string)
 263
 264 The cache key prefix that the cache middleware should use. See the
 265 `cache docs`_.
 266
 267 CACHE_MIDDLEWARE_SECONDS
 268 ------------------------
 269
 270 Default: ``600``
 271
 272 The default number of seconds to cache a page when the caching middleware or
 273 ``cache_page()`` decorator is used.
 274
 275 DATABASE_ENGINE
 276 ---------------
 277
 278 Default: ``''`` (Empty string)
 279
 280 The database backend to use. The build-in database backends are
 281 ``'postgresql_psycopg2'``, ``'postgresql'``, ``'mysql'``, ``'sqlite3'``, and
 282 ``'oracle'``.
 283
 284 In the Django development version, you can use a database backend that doesn't
 285 ship with Django by setting ``DATABASE_ENGINE`` to a fully-qualified path (i.e.
 286 ``mypackage.backends.whatever``). Writing a whole new database backend from
 287 scratch is left as an exercise to the reader; see the other backends for
 288 examples.
 289
 290 DATABASE_HOST
 291 -------------
 292
 293 Default: ``''`` (Empty string)
 294
 295 Which host to use when connecting to the database. An empty string means
 296 localhost. Not used with SQLite.
 297
 298 If this value starts with a forward slash (``'/'``) and you're using MySQL,
 299 MySQL will connect via a Unix socket to the specified socket. For example::
 300
 301     DATABASE_HOST = '/var/run/mysql'
 302
 303 If you're using MySQL and this value *doesn't* start with a forward slash, then
 304 this value is assumed to be the host.
 305
 306 If you're using PostgreSQL, an empty string means to use a Unix domain socket
 307 for the connection, rather than a network connection to localhost. If you
 308 explictly need to use a TCP/IP connection on the local machine with
 309 PostgreSQL, specify ``localhost`` here.
 310
 311 DATABASE_NAME
 312 -------------
 313
 314 Default: ``''`` (Empty string)
 315
 316 The name of the database to use. For SQLite, it's the full path to the database
 317 file.
 318
 319 DATABASE_OPTIONS
 320 ----------------
 321
 322 Default: ``{}`` (Empty dictionary)
 323
 324 Extra parameters to use when connecting to the database. Consult backend
 325 module's document for available keywords.
 326
 327 DATABASE_PASSWORD
 328 -----------------
 329
 330 Default: ``''`` (Empty string)
 331
 332 The password to use when connecting to the database. Not used with SQLite.
 333
 334 DATABASE_PORT
 335 -------------
 336
 337 Default: ``''`` (Empty string)
 338
 339 The port to use when connecting to the database. An empty string means the
 340 default port. Not used with SQLite.
 341
 342 DATABASE_USER
 343 -------------
 344
 345 Default: ``''`` (Empty string)
 346
 347 The username to use when connecting to the database. Not used with SQLite.
 348
 349 DATE_FORMAT
 350 -----------
 351
 352 Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``)
 353
 354 The default formatting to use for date fields on Django admin change-list
 355 pages -- and, possibly, by other parts of the system. See
 356 `allowed date format strings`_.
 357
 358 See also ``DATETIME_FORMAT``, ``TIME_FORMAT``, ``YEAR_MONTH_FORMAT``
 359 and ``MONTH_DAY_FORMAT``.
 360
 361 .. _allowed date format strings: ../templates/#now
 362
 363 DATETIME_FORMAT
 364 ---------------
 365
 366 Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``)
 367
 368 The default formatting to use for datetime fields on Django admin change-list
 369 pages -- and, possibly, by other parts of the system. See
 370 `allowed date format strings`_.
 371
 372 See also ``DATE_FORMAT``, ``DATETIME_FORMAT``, ``TIME_FORMAT``,
 373 ``YEAR_MONTH_FORMAT`` and ``MONTH_DAY_FORMAT``.
 374
 375 .. _allowed date format strings: ../templates/#now
 376
 377 DEBUG
 378 -----
 379
 380 Default: ``False``
 381
 382 A boolean that turns on/off debug mode.
 383
 384 If you define custom settings, django/views/debug.py has a ``HIDDEN_SETTINGS``
 385 regular expression which will hide from the DEBUG view anything that contains
 386 ``'SECRET'``, ``'PASSWORD'``, or ``'PROFANITIES'``. This allows untrusted users to
 387 be able to give backtraces without seeing sensitive (or offensive) settings.
 388
 389 Still, note that there are always going to be sections of your debug output that
 390 are inappropriate for public consumption. File paths, configuration options, and
 391 the like all give attackers extra information about your server.
 392
 393 It is also important to remember that when running with ``DEBUG`` turned on, Django
 394 will remember every SQL query it executes. This is useful when you are debugging,
 395 but on a production server, it will rapidly consume memory.
 396
 397 Never deploy a site into production with ``DEBUG`` turned on.
 398
 399 DEBUG_PROPAGATE_EXCEPTIONS
 400 --------------------------
 401
 402 **New in Django development version**
 403
 404 Default: ``False``
 405
 406 If set to True, Django's normal exception handling of view functions
 407 will be suppressed, and exceptions will propagate upwards.  This can
 408 be useful for some test setups, and should never be used on a live
 409 site.
 410
 411 DEFAULT_CHARSET
 412 ---------------
 413
 414 Default: ``'utf-8'``
 415
 416 Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't
 417 manually specified. Used with ``DEFAULT_CONTENT_TYPE`` to construct the
 418 ``Content-Type`` header.
 419
 420 DEFAULT_CONTENT_TYPE
 421 --------------------
 422
 423 Default: ``'text/html'``
 424
 425 Default content type to use for all ``HttpResponse`` objects, if a MIME type
 426 isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the
 427 ``Content-Type`` header.
 428
 429 DEFAULT_FILE_STORAGE
 430 --------------------
 431
 432 Default: ``'django.core.filestorage.filesystem.FileSystemStorage'``
 433
 434 Default file storage class to be used for any file-related operations that don't
 435 specify a particular storage system. See the `file documentation`_ for details.
 436
 437 .. _file documentation: ../files/
 438
 439 DEFAULT_FROM_EMAIL
 440 ------------------
 441
 442 Default: ``'webmaster@localhost'``
 443
 444 Default e-mail address to use for various automated correspondence from the
 445 site manager(s).
 446
 447 DEFAULT_TABLESPACE
 448 ------------------
 449
 450 **New in Django development version**
 451
 452 Default: ``''`` (Empty string)
 453
 454 Default tablespace to use for models that don't specify one, if the
 455 backend supports it.
 456
 457 DEFAULT_INDEX_TABLESPACE
 458 ------------------------
 459
 460 **New in Django development version**
 461
 462 Default: ``''`` (Empty string)
 463
 464 Default tablespace to use for indexes on fields that don't specify
 465 one, if the backend supports it.
 466
 467 DISALLOWED_USER_AGENTS
 468 ----------------------
 469
 470 Default: ``()`` (Empty tuple)
 471
 472 List of compiled regular expression objects representing User-Agent strings
 473 that are not allowed to visit any page, systemwide. Use this for bad
 474 robots/crawlers.  This is only used if ``CommonMiddleware`` is installed (see
 475 the `middleware docs`_).
 476
 477 EMAIL_HOST
 478 ----------
 479
 480 Default: ``'localhost'``
 481
 482 The host to use for sending e-mail.
 483
 484 See also ``EMAIL_PORT``.
 485
 486 EMAIL_HOST_PASSWORD
 487 -------------------
 488
 489 Default: ``''`` (Empty string)
 490
 491 Password to use for the SMTP server defined in ``EMAIL_HOST``. This setting is
 492 used in conjunction with ``EMAIL_HOST_USER`` when authenticating to the SMTP
 493 server. If either of these settings is empty, Django won't attempt
 494 authenticaion.
 495
 496 See also ``EMAIL_HOST_USER``.
 497
 498 EMAIL_HOST_USER
 499 ---------------
 500
 501 Default: ``''`` (Empty string)
 502
 503 Username to use for the SMTP server defined in ``EMAIL_HOST``. If empty,
 504 Django won't attempt authentication.
 505
 506 See also ``EMAIL_HOST_PASSWORD``.
 507
 508 EMAIL_PORT
 509 ----------
 510
 511 Default: ``25``
 512
 513 Port to use for the SMTP server defined in ``EMAIL_HOST``.
 514
 515 EMAIL_SUBJECT_PREFIX
 516 --------------------
 517
 518 Default: ``'[Django] '``
 519
 520 Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins``
 521 or ``django.core.mail.mail_managers``. You'll probably want to include the
 522 trailing space.
 523
 524 EMAIL_USE_TLS
 525 -------------
 526
 527 **New in Django development version**
 528
 529 Default: ``False``
 530
 531 Whether to use a TLS (secure) connection when talking to the SMTP server.
 532
 533 FILE_CHARSET
 534 ------------
 535
 536 **New in Django development version**
 537
 538 Default: ``'utf-8'``
 539
 540 The character encoding used to decode any files read from disk. This includes
 541 template files and initial SQL data files.
 542
 543 FILE_UPLOAD_HANDLERS
 544 --------------------
 545
 546 **New in Django development version**
 547
 548 Default::
 549
 550     ("django.core.files.uploadhandler.MemoryFileUploadHandler",
 551      "django.core.files.uploadhandler.TemporaryFileUploadHandler",)
 552
 553 A tuple of handlers to use for uploading. See `file uploads`_ for details.
 554
 555 .. _file uploads: ../upload_handling/
 556
 557 FILE_UPLOAD_MAX_MEMORY_SIZE
 558 ---------------------------
 559
 560 **New in Django development version**
 561
 562 Default: ``2621440`` (i.e. 2.5 MB).
 563
 564 The maximum size (in bytes) that an upload will be before it gets streamed to
 565 the file system. See `file uploads`_ for details.
 566
 567 FILE_UPLOAD_TEMP_DIR
 568 --------------------
 569
 570 **New in Django development version**
 571
 572 Default: ``None``
 573
 574 The directory to store data temporarily while uploading files. If ``None``,
 575 Django will use the standard temporary directory for the operating system. For
 576 example, this will default to '/tmp' on \*nix-style operating systems.
 577
 578 See `file uploads`_ for details.
 579
 580 FIXTURE_DIRS
 581 -------------
 582
 583 Default: ``()`` (Empty tuple)
 584
 585 List of locations of the fixture data files, in search order. Note that
 586 these paths should use Unix-style forward slashes, even on Windows. See
 587 `Testing Django Applications`_.
 588
 589 .. _Testing Django Applications: ../testing/
 590
 591 FORCE_SCRIPT_NAME
 592 ------------------
 593
 594 Default: ``None``
 595
 596 If not ``None``, this will be used as the value of the ``SCRIPT_NAME``
 597 environment variable in any HTTP request. This setting can be used to override
 598 the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version
 599 of the preferred value or not supplied at all.
 600
 601 IGNORABLE_404_ENDS
 602 ------------------
 603
 604 Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')``
 605
 606 See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``.
 607
 608 IGNORABLE_404_STARTS
 609 --------------------
 610
 611 Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')``
 612
 613 A tuple of strings that specify beginnings of URLs that should be ignored by
 614 the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and
 615 the section on `error reporting via e-mail`_.
 616
 617 INSTALLED_APPS
 618 --------------
 619
 620 Default: ``()`` (Empty tuple)
 621
 622 A tuple of strings designating all applications that are enabled in this Django
 623 installation. Each string should be a full Python path to a Python package that
 624 contains a Django application, as created by `django-admin.py startapp`_.
 625
 626 .. _django-admin.py startapp: ../django-admin/#startapp-appname
 627
 628 INTERNAL_IPS
 629 ------------
 630
 631 Default: ``()`` (Empty tuple)
 632
 633 A tuple of IP addresses, as strings, that:
 634
 635     * See debug comments, when ``DEBUG`` is ``True``
 636     * Receive X headers if the ``XViewMiddleware`` is installed (see the
 637       `middleware docs`_)
 638
 639 JING_PATH
 640 ---------
 641
 642 Default: ``'/usr/bin/jing'``
 643
 644 Path to the "Jing" executable. Jing is a RELAX NG validator, and Django uses it
 645 to validate each ``XMLField`` in your models.
 646 See http://www.thaiopensource.com/relaxng/jing.html .
 647
 648 LANGUAGE_CODE
 649 -------------
 650
 651 Default: ``'en-us'``
 652
 653 A string representing the language code for this installation. This should be
 654 in standard language format. For example, U.S. English is ``"en-us"``. See the
 655 `internationalization docs`_.
 656
 657 .. _internationalization docs: ../i18n/
 658
 659 LANGUAGE_COOKIE_NAME
 660 --------------------
 661
 662 **New in Django development version**
 663
 664 Default: ``'django_language'``
 665
 666 The name of the cookie to use for the language cookie. This can be whatever
 667 you want (but should be different from ``SESSION_COOKIE_NAME``). See the
 668 `internationalization docs`_ for details.
 669
 670 LANGUAGES
 671 ---------
 672
 673 Default: A tuple of all available languages. This list is continually growing
 674 and including a copy here would inevitably become rapidly out of date. You can
 675 see the current list of translated languages by looking in
 676 ``django/conf/global_settings.py`` (or view the `online source`_).
 677
 678 .. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py
 679
 680 The list is a tuple of two-tuples in the format (language code, language
 681 name) -- for example, ``('ja', 'Japanese')``. This specifies which languages
 682 are available for language selection. See the `internationalization docs`_ for
 683 details.
 684
 685 Generally, the default value should suffice. Only set this setting if you want
 686 to restrict language selection to a subset of the Django-provided languages.
 687
 688 If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as
 689 translation strings (as in the default value displayed above) -- but use a
 690 "dummy" ``gettext()`` function, not the one in ``django.utils.translation``.
 691 You should *never* import ``django.utils.translation`` from within your
 692 settings file, because that module in itself depends on the settings, and that
 693 would cause a circular import.
 694
 695 The solution is to use a "dummy" ``gettext()`` function. Here's a sample
 696 settings file::
 697
 698     gettext = lambda s: s
 699
 700     LANGUAGES = (
 701         ('de', gettext('German')),
 702         ('en', gettext('English')),
 703     )
 704
 705 With this arrangement, ``django-admin.py makemessages`` will still find and
 706 mark these strings for translation, but the translation won't happen at
 707 runtime -- so you'll have to remember to wrap the languages in the *real*
 708 ``gettext()`` in any code that uses ``LANGUAGES`` at runtime.
 709
 710 LOCALE_PATHS
 711 ------------
 712
 713 Default: ``()`` (Empty tuple)
 714
 715 A tuple of directories where Django looks for translation files.
 716 See the `internationalization docs section`_ explaining the variable and the
 717 default behavior.
 718
 719 .. _internationalization docs section: ../i18n/#using-translations-in-your-own-projects
 720
 721 LOGIN_REDIRECT_URL
 722 ------------------
 723
 724 **New in Django development version**
 725
 726 Default: ``'/accounts/profile/'``
 727
 728 The URL where requests are redirected after login when the
 729 ``contrib.auth.login`` view gets no ``next`` parameter.
 730
 731 This is used by the `@login_required`_ decorator, for example.
 732
 733 LOGIN_URL
 734 ---------
 735
 736 **New in Django development version**
 737
 738 Default: ``'/accounts/login/'``
 739
 740 The URL where requests are redirected for login, specially when using the
 741 `@login_required`_ decorator.
 742
 743 LOGOUT_URL
 744 ----------
 745
 746 **New in Django development version**
 747
 748 Default: ``'/accounts/logout/'``
 749
 750 LOGIN_URL counterpart.
 751
 752 MANAGERS
 753 --------
 754
 755 Default: ``()`` (Empty tuple)
 756
 757 A tuple in the same format as ``ADMINS`` that specifies who should get
 758 broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``.
 759
 760 MEDIA_ROOT
 761 ----------
 762
 763 Default: ``''`` (Empty string)
 764
 765 Absolute path to the directory that holds media for this installation.
 766 Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``.
 767
 768 MEDIA_URL
 769 ---------
 770
 771 Default: ``''`` (Empty string)
 772
 773 URL that handles the media served from ``MEDIA_ROOT``.
 774 Example: ``"http://media.lawrence.com"``
 775
 776 Note that this should have a trailing slash if it has a path component.
 777
 778 Good: ``"http://www.example.com/static/"``
 779 Bad: ``"http://www.example.com/static"``
 780
 781 MIDDLEWARE_CLASSES
 782 ------------------
 783
 784 Default::
 785
 786     ("django.contrib.sessions.middleware.SessionMiddleware",
 787      "django.contrib.auth.middleware.AuthenticationMiddleware",
 788      "django.middleware.common.CommonMiddleware",
 789      "django.middleware.doc.XViewMiddleware")
 790
 791 A tuple of middleware classes to use. See the `middleware docs`_.
 792
 793 MONTH_DAY_FORMAT
 794 ----------------
 795
 796 Default: ``'F j'``
 797
 798 The default formatting to use for date fields on Django admin change-list
 799 pages -- and, possibly, by other parts of the system -- in cases when only the
 800 month and day are displayed.
 801
 802 For example, when a Django admin change-list page is being filtered by a date
 803 drilldown, the header for a given day displays the day and month. Different
 804 locales have different formats. For example, U.S. English would say
 805 "January 1," whereas Spanish might say "1 Enero."
 806
 807 See `allowed date format strings`_. See also ``DATE_FORMAT``,
 808 ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``YEAR_MONTH_FORMAT``.
 809
 810 PREPEND_WWW
 811 -----------
 812
 813 Default: ``False``
 814
 815 Whether to prepend the "www." subdomain to URLs that don't have it. This is
 816 only used if ``CommonMiddleware`` is installed (see the `middleware docs`_).
 817 See also ``APPEND_SLASH``.
 818
 819 PROFANITIES_LIST
 820 ----------------
 821
 822 A tuple of profanities, as strings, that will trigger a validation error when
 823 the ``hasNoProfanities`` validator is called.
 824
 825 We don't list the default values here, because that would be profane. To see
 826 the default values, see the file ``django/conf/global_settings.py``.
 827
 828 ROOT_URLCONF
 829 ------------
 830
 831 Default: Not defined
 832
 833 A string representing the full Python import path to your root URLconf. For example:
 834 ``"mydjangoapps.urls"``. Can be overridden on a per-request basis by
 835 setting the attribute ``urlconf`` on the incoming ``HttpRequest``
 836 object. See `How Django processes a request`_ for details.
 837
 838 .. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
 839
 840 SECRET_KEY
 841 ----------
 842
 843 Default: ``''`` (Empty string)
 844
 845 A secret key for this particular Django installation. Used to provide a seed in
 846 secret-key hashing algorithms. Set this to a random string -- the longer, the
 847 better. ``django-admin.py startproject`` creates one automatically.
 848
 849 SEND_BROKEN_LINK_EMAILS
 850 -----------------------
 851
 852 Default: ``False``
 853
 854 Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a
 855 Django-powered page that is 404ed with a non-empty referer (i.e., a broken
 856 link). This is only used if ``CommonMiddleware`` is installed (see the
 857 `middleware docs`_). See also ``IGNORABLE_404_STARTS``,
 858 ``IGNORABLE_404_ENDS`` and the section on `error reporting via e-mail`_
 859
 860 SERIALIZATION_MODULES
 861 ---------------------
 862
 863 Default: Not defined.
 864
 865 A dictionary of modules containing serializer definitions (provided as
 866 strings), keyed by a string identifier for that serialization type. For
 867 example, to define a YAML serializer, use::
 868
 869     SERIALIZATION_MODULES = { 'yaml' : 'path.to.yaml_serializer' }
 870
 871 SERVER_EMAIL
 872 ------------
 873
 874 Default: ``'root@localhost'``
 875
 876 The e-mail address that error messages come from, such as those sent to
 877 ``ADMINS`` and ``MANAGERS``.
 878
 879 SESSION_ENGINE
 880 --------------
 881
 882 **New in Django development version**
 883
 884 Default: ``django.contrib.sessions.backends.db``
 885
 886 Controls where Django stores session data. Valid values are:
 887
 888     * ``'django.contrib.sessions.backends.db'``
 889     * ``'django.contrib.sessions.backends.file'``
 890     * ``'django.contrib.sessions.backends.cache'``
 891
 892 See the `session docs`_ for more details.
 893
 894 SESSION_COOKIE_AGE
 895 ------------------
 896
 897 Default: ``1209600`` (2 weeks, in seconds)
 898
 899 The age of session cookies, in seconds. See the `session docs`_.
 900
 901 SESSION_COOKIE_DOMAIN
 902 ---------------------
 903
 904 Default: ``None``
 905
 906 The domain to use for session cookies. Set this to a string such as
 907 ``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard
 908 domain cookie. See the `session docs`_.
 909
 910 SESSION_COOKIE_NAME
 911 -------------------
 912
 913 Default: ``'sessionid'``
 914
 915 The name of the cookie to use for sessions. This can be whatever you want (but
 916 should be different from ``LANGUAGE_COOKIE_NAME``). See the `session docs`_.
 917
 918 SESSION_COOKIE_PATH
 919 -------------------
 920
 921 **New in Django development version**
 922
 923 Default: ``'/'``
 924
 925 The path set on the session cookie. This should either match the URL path of your
 926 Django installation or be parent of that path.
 927
 928 This is useful if you have multiple Django instances running under the same
 929 hostname. They can use different cookie paths, and each instance will only see
 930 its own session cookie.
 931
 932 SESSION_COOKIE_SECURE
 933 ---------------------
 934
 935 Default: ``False``
 936
 937 Whether to use a secure cookie for the session cookie. If this is set to
 938 ``True``, the cookie will be marked as "secure," which means browsers may
 939 ensure that the cookie is only sent under an HTTPS connection.
 940 See the `session docs`_.
 941
 942 SESSION_EXPIRE_AT_BROWSER_CLOSE
 943 -------------------------------
 944
 945 Default: ``False``
 946
 947 Whether to expire the session when the user closes his or her browser.
 948 See the `session docs`_.
 949
 950 SESSION_FILE_PATH
 951 -----------------
 952
 953 **New in Django development version**
 954
 955 Default: ``/tmp/``
 956
 957 If you're using file-based session storage, this sets the directory in
 958 which Django will store session data. See the `session docs`_ for
 959 more details.
 960
 961 SESSION_SAVE_EVERY_REQUEST
 962 --------------------------
 963
 964 Default: ``False``
 965
 966 Whether to save the session data on every request. See the `session docs`_.
 967
 968 SITE_ID
 969 -------
 970
 971 Default: Not defined
 972
 973 The ID, as an integer, of the current site in the ``django_site`` database
 974 table. This is used so that application data can hook into specific site(s)
 975 and a single database can manage content for multiple sites.
 976
 977 See the `site framework docs`_.
 978
 979 .. _site framework docs: ../sites/
 980
 981 TEMPLATE_CONTEXT_PROCESSORS
 982 ---------------------------
 983
 984 Default::
 985
 986     ("django.core.context_processors.auth",
 987     "django.core.context_processors.debug",
 988     "django.core.context_processors.i18n",
 989     "django.core.context_processors.media")
 990
 991 A tuple of callables that are used to populate the context in ``RequestContext``.
 992 These callables take a request object as their argument and return a dictionary
 993 of items to be merged into the context.
 994
 995 TEMPLATE_DEBUG
 996 --------------
 997
 998 Default: ``False``
 999
1000 A boolean that turns on/off template debug mode. If this is ``True``, the fancy
1001 error page will display a detailed report for any ``TemplateSyntaxError``. This
1002 report contains the relevant snippet of the template, with the appropriate line
1003 highlighted.
1004
1005 Note that Django only displays fancy error pages if ``DEBUG`` is ``True``, so
1006 you'll want to set that to take advantage of this setting.
1007
1008 See also ``DEBUG``.
1009
1010 TEMPLATE_DIRS
1011 -------------
1012
1013 Default: ``()`` (Empty tuple)
1014
1015 List of locations of the template source files, in search order. Note that
1016 these paths should use Unix-style forward slashes, even on Windows.
1017
1018 See the `template documentation`_.
1019
1020 TEMPLATE_LOADERS
1021 ----------------
1022
1023 Default::
1024
1025      ('django.template.loaders.filesystem.load_template_source',
1026       'django.template.loaders.app_directories.load_template_source')
1027
1028 A tuple of callables (as strings) that know how to import templates from
1029 various sources. See the `template documentation`_.
1030
1031 TEMPLATE_STRING_IF_INVALID
1032 --------------------------
1033
1034 Default: ``''`` (Empty string)
1035
1036 Output, as a string, that the template system should use for invalid (e.g.
1037 misspelled) variables. See `How invalid variables are handled`_.
1038
1039 .. _How invalid variables are handled: ../templates_python/#how-invalid-variables-are-handled
1040
1041 TEST_DATABASE_CHARSET
1042 ---------------------
1043
1044 **New in Django development version**
1045
1046 Default: ``None``
1047
1048 The character set encoding used to create the test database. The value of this
1049 string is passed directly through to the database, so its format is
1050 backend-specific.
1051
1052 Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and MySQL_ (``mysql``) backends.
1053
1054 .. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html
1055 .. _MySQL: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
1056
1057 TEST_DATABASE_COLLATION
1058 ------------------------
1059
1060 **New in Django development version**
1061
1062 Default: ``None``
1063
1064 The collation order to use when creating the test database. This value is
1065 passed directly to the backend, so its format is backend-specific.
1066
1067 Only supported for the ``mysql`` backend (see `section 10.3.2`_ of the MySQL
1068 manual for details).
1069
1070 .. _section 10.3.2: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
1071
1072 TEST_DATABASE_NAME
1073 ------------------
1074
1075 Default: ``None``
1076
1077 The name of database to use when running the test suite.
1078
1079 If the default value (``None``) is used with the SQLite database engine, the
1080 tests will use a memory resident database. For all other database engines the
1081 test database will use the name ``'test_' + settings.DATABASE_NAME``.
1082
1083 See `Testing Django Applications`_.
1084
1085 .. _Testing Django Applications: ../testing/
1086
1087 TEST_RUNNER
1088 -----------
1089
1090 Default: ``'django.test.simple.run_tests'``
1091
1092 The name of the method to use for starting the test suite. See
1093 `Testing Django Applications`_.
1094
1095 .. _Testing Django Applications: ../testing/
1096
1097 TIME_FORMAT
1098 -----------
1099
1100 Default: ``'P'`` (e.g. ``4 p.m.``)
1101
1102 The default formatting to use for time fields on Django admin change-list
1103 pages -- and, possibly, by other parts of the system. See
1104 `allowed date format strings`_.
1105
1106 See also ``DATE_FORMAT``, ``DATETIME_FORMAT``, ``TIME_FORMAT``,
1107 ``YEAR_MONTH_FORMAT`` and ``MONTH_DAY_FORMAT``.
1108
1109 .. _allowed date format strings: ../templates/#now
1110
1111 TIME_ZONE
1112 ---------
1113
1114 Default: ``'America/Chicago'``
1115
1116 A string representing the time zone for this installation. `See available choices`_.
1117 (Note that list of available choices lists more than one on the same line;
1118 you'll want to use just one of the choices for a given time zone. For instance,
1119 one line says ``'Europe/London GB GB-Eire'``, but you should use the first bit
1120 of that -- ``'Europe/London'`` -- as your ``TIME_ZONE`` setting.)
1121
1122 Note that this is the time zone to which Django will convert all dates/times --
1123 not necessarily the timezone of the server. For example, one server may serve
1124 multiple Django-powered sites, each with a separate time-zone setting.
1125
1126 Normally, Django sets the ``os.environ['TZ']`` variable to the time zone you
1127 specify in the  ``TIME_ZONE`` setting. Thus, all your views and models will
1128 automatically operate in the correct time zone. However, if you're using the
1129 manual configuration option (see below), Django will *not* touch the ``TZ``
1130 environment variable, and it'll be up to you to ensure your processes are
1131 running in the correct environment.
1132
1133 .. note::
1134     Django cannot reliably use alternate time zones in a Windows environment.
1135     If you're running Django on Windows, this variable must be set to match the
1136     system timezone.
1137
1138 URL_VALIDATOR_USER_AGENT
1139 ------------------------
1140
1141 Default: ``Django/<version> (http://www.djangoproject.com/)``
1142
1143 The string to use as the ``User-Agent`` header when checking to see if URLs
1144 exist (see the ``verify_exists`` option on URLField_).
1145
1146 .. _URLField: ../model-api/#urlfield
1147
1148 USE_ETAGS
1149 ---------
1150
1151 Default: ``False``
1152
1153 A boolean that specifies whether to output the "Etag" header. This saves
1154 bandwidth but slows down performance. This is only used if ``CommonMiddleware``
1155 is installed (see the `middleware docs`_).
1156
1157 USE_I18N
1158 --------
1159
1160 Default: ``True``
1161
1162 A boolean that specifies whether Django's internationalization system should be
1163 enabled. This provides an easy way to turn it off, for performance. If this is
1164 set to ``False``, Django will make some optimizations so as not to load the
1165 internationalization machinery.
1166
1167 YEAR_MONTH_FORMAT
1168 -----------------
1169
1170 Default: ``'F Y'``
1171
1172 The default formatting to use for date fields on Django admin change-list
1173 pages -- and, possibly, by other parts of the system -- in cases when only the
1174 year and month are displayed.
1175
1176 For example, when a Django admin change-list page is being filtered by a date
1177 drilldown, the header for a given month displays the month and the year.
1178 Different locales have different formats. For example, U.S. English would say
1179 "January 2006," whereas another locale might say "2006/January."
1180
1181 See `allowed date format strings`_. See also ``DATE_FORMAT``,
1182 ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``MONTH_DAY_FORMAT``.
1183
1184 .. _cache docs: ../cache/
1185 .. _middleware docs: ../middleware/
1186 .. _session docs: ../sessions/
1187 .. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
1188 .. _template documentation: ../templates_python/
1189
1190 Creating your own settings
1191 ==========================
1192
1193 There's nothing stopping you from creating your own settings, for your own
1194 Django apps. Just follow these conventions:
1195
1196     * Setting names are in all uppercase.
1197     * For settings that are sequences, use tuples instead of lists. This is
1198       purely for performance.
1199     * Don't reinvent an already-existing setting.
1200
1201 Using settings without setting DJANGO_SETTINGS_MODULE
1202 =====================================================
1203
1204 In some cases, you might want to bypass the ``DJANGO_SETTINGS_MODULE``
1205 environment variable. For example, if you're using the template system by
1206 itself, you likely don't want to have to set up an environment variable
1207 pointing to a settings module.
1208
1209 In these cases, you can configure Django's settings manually. Do this by
1210 calling ``django.conf.settings.configure()``.
1211
1212 Example::
1213
1214     from django.conf import settings
1215
1216     settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,
1217         TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))
1218
1219 Pass ``configure()`` as many keyword arguments as you'd like, with each keyword
1220 argument representing a setting and its value. Each argument name should be all
1221 uppercase, with the same name as the settings described above. If a particular
1222 setting is not passed to ``configure()`` and is needed at some later point,
1223 Django will use the default setting value.
1224
1225 Configuring Django in this fashion is mostly necessary -- and, indeed,
1226 recommended -- when you're using a piece of the framework inside a larger
1227 application.
1228
1229 Consequently, when configured via ``settings.configure()``, Django will not
1230 make any modifications to the process environment variables. (See the
1231 explanation of ``TIME_ZONE``, above, for why this would normally occur.) It's
1232 assumed that you're already in full control of your environment in these cases.
1233
1234 Custom default settings
1235 -----------------------
1236
1237 If you'd like default values to come from somewhere other than
1238 ``django.conf.global_settings``, you can pass in a module or class that
1239 provides the default settings as the ``default_settings`` argument (or as the
1240 first positional argument) in the call to ``configure()``.
1241
1242 In this example, default settings are taken from ``myapp_defaults``, and the
1243 ``DEBUG`` setting is set to ``True``, regardless of its value in
1244 ``myapp_defaults``::
1245
1246     from django.conf import settings
1247     from myapp import myapp_defaults
1248
1249     settings.configure(default_settings=myapp_defaults, DEBUG=True)
1250
1251 The following example, which uses ``myapp_defaults`` as a positional argument,
1252 is equivalent::
1253
1254     settings.configure(myapp_defaults, DEBUG = True)
1255
1256 Normally, you will not need to override the defaults in this fashion. The
1257 Django defaults are sufficiently tame that you can safely use them. Be aware
1258 that if you do pass in a new default module, it entirely *replaces* the Django
1259 defaults, so you must specify a value for every possible setting that might be
1260 used in that code you are importing. Check in
1261 ``django.conf.settings.global_settings`` for the full list.
1262
1263 Either configure() or DJANGO_SETTINGS_MODULE is required
1264 --------------------------------------------------------
1265
1266 If you're not setting the ``DJANGO_SETTINGS_MODULE`` environment variable, you
1267 *must* call ``configure()`` at some point before using any code that reads
1268 settings.
1269
1270 If you don't set ``DJANGO_SETTINGS_MODULE`` and don't call ``configure()``,
1271 Django will raise an ``ImportError`` exception the first time a setting
1272 is accessed.
1273
1274 If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then*
1275 call ``configure()``, Django will raise a ``RuntimeError`` indicating
1276 that settings have already been configured.
1277
1278 Also, it's an error to call ``configure()`` more than once, or to call
1279 ``configure()`` after any setting has been accessed.
1280
1281 It boils down to this: Use exactly one of either ``configure()`` or
1282 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
1283
1284 .. _@login_required: ../authentication/#the-login-required-decorator
1285
1286 Error reporting via e-mail
1287 ==========================
1288
1289 Server errors
1290 -------------
1291
1292 When ``DEBUG`` is ``False``, Django will e-mail the users listed in the
1293 ``ADMIN`` setting whenever your code raises an unhandled exception and results
1294 in an internal server error (HTTP status code 500). This gives the
1295 administrators immediate notification of any errors.
1296
1297 To disable this behavior, just remove all entries from the ``ADMINS`` setting.
1298
1299 404 errors
1300 ----------
1301
1302 When ``DEBUG`` is ``False``, ``SEND_BROKEN_LINK_EMAILS`` is ``True`` and your
1303 ``MIDDLEWARE_CLASSES`` setting includes ``CommonMiddleware``, Django will
1304 e-mail the users listed in the ``MANAGERS`` setting whenever your code raises
1305 a 404 and the request has a referer. (It doesn't bother to e-mail for 404s
1306 that don't have a referer.)
1307
1308 You can tell Django to stop reporting particular 404s by tweaking the
1309 ``IGNORABLE_404_ENDS`` and ``IGNORABLE_404_STARTS`` settings. Both should be a
1310 tuple of strings. For example::
1311
1312     IGNORABLE_404_ENDS = ('.php', '.cgi')
1313     IGNORABLE_404_STARTS = ('/phpmyadmin/',)
1314
1315 In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not*
1316 be reported. Neither will any URL starting with ``/phpmyadmin/``.
1317
1318 To disable this behavior, just remove all entries from the ``MANAGERS`` setting.