docs/ref/settings.txt

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