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 shouldn't have 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 ``"myproject.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=myproject.settings
  51     django-admin.py runserver
  52
  53 Example (Windows shell)::
  54
  55     set DJANGO_SETTINGS_MODULE=myproject.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=myproject.settings
  61
  62 .. _django-admin.py: http://www.djangoproject.com/documentation/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 myproject.settings
  74     </Location>
  75
  76 Read the `Django mod_python documentation`_ for more information.
  77
  78 .. _Django mod_python documentation: http://www.djangoproject.com/documentation/mod_python/
  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 Using settings in Python code
  97 =============================
  98
  99 In your Django apps, use settings by importing them from
 100 ``django.conf.settings``. Example::
 101
 102     from django.conf.settings import DEBUG
 103
 104     if DEBUG:
 105         # Do something
 106
 107 Note that your code should *not* import from either ``global_settings`` or
 108 your own settings file. ``django.conf.settings`` abstracts the concepts of
 109 default settings and site-specific settings; it presents a single interface.
 110
 111 Altering settings at runtime
 112 ============================
 113
 114 You shouldn't alter settings in your applications at runtime. For example,
 115 don't do this in a view::
 116
 117     from django.conf.settings import DEBUG
 118
 119     DEBUG = True   # Don't do this!
 120
 121 The only place you should assign to settings is in a settings file.
 122
 123 Security
 124 ========
 125
 126 Because a settings file contains sensitive information, such as the database
 127 password, you should make every attempt to limit access to it. For example,
 128 change its file permissions so that only you and your Web server's user can
 129 read it. This is especially important in a shared-hosting environment.
 130
 131 Available settings
 132 ==================
 133
 134 Here's a full list of all available settings, in alphabetical order, and their
 135 default values.
 136
 137 ABSOLUTE_URL_OVERRIDES
 138 ----------------------
 139
 140 Default: ``{}`` (Empty dictionary)
 141
 142 A dictionary mapping ``"app_label.module_name"`` strings to functions that take
 143 a model object and return its URL. This is a way of overriding
 144 ``get_absolute_url()`` methods on a per-installation basis. Example::
 145
 146     ABSOLUTE_URL_OVERRIDES = {
 147         'blogs.blogs': lambda o: "/blogs/%s/" % o.slug,
 148         'news.stories': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
 149     }
 150
 151 ADMIN_FOR
 152 ---------
 153
 154 Default: ``()`` (Empty list)
 155
 156 Used for admin-site settings modules, this should be a tuple of settings
 157 modules (in the format ``'foo.bar.baz'``) for which this site is an admin.
 158
 159 ADMIN_MEDIA_PREFIX
 160 ------------------
 161
 162 Default: ``'/media/'``
 163
 164 The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use
 165 a trailing slash.
 166
 167 ADMINS
 168 ------
 169
 170 Default: ``()`` (Empty tuple)
 171
 172 A tuple that lists people who get code error notifications. When
 173 ``DEBUG=False`` and a view raises an exception, Django will e-mail these people
 174 with the full exception information. Each member of the tuple should be a tuple
 175 of (Full name, e-mail address). Example::
 176
 177     (('John', 'john@example.com'), ('Mary', 'mary@example.com'))
 178
 179 ALLOWED_INCLUDE_ROOTS
 180 ---------------------
 181
 182 Default: ``()`` (Empty tuple)
 183
 184 A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template
 185 tag. This is a security measure, so that template authors can't access files
 186 that they shouldn't be accessing.
 187
 188 For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``,
 189 then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}``
 190 wouldn't.
 191
 192 APPEND_SLASH
 193 ------------
 194
 195 Default: ``True``
 196
 197 Whether to append trailing slashes to URLs. This is only used if
 198 ``CommonMiddleware`` is installed (see the `middleware docs`_). See also
 199 ``PREPEND_WWW``.
 200
 201 CACHE_BACKEND
 202 -------------
 203
 204 Default: ``'simple://'``
 205
 206 The cache backend to use. See the `cache docs`_.
 207
 208 CACHE_MIDDLEWARE_KEY_PREFIX
 209
 210 Default: ``''`` (Empty string)
 211
 212 The cache key prefix that the cache middleware should use. See the
 213 `cache docs`_.
 214
 215 DATABASE_ENGINE
 216 ---------------
 217
 218 Default: ``'postgresql'``
 219
 220 Which database backend to use. Either ``'postgresql'``, ``'mysql'``,
 221 ``'sqlite3'`` or ``'ado_mssql'``.
 222
 223 DATABASE_HOST
 224 -------------
 225
 226 Default: ``''`` (Empty string)
 227
 228 Which host to use when connecting to the database. An empty string means
 229 localhost. Not used with SQLite.
 230
 231 DATABASE_NAME
 232 -------------
 233
 234 Default: ``''`` (Empty string)
 235
 236 The name of the database to use. For SQLite, it's the full path to the database
 237 file.
 238
 239 DATABASE_PASSWORD
 240 -----------------
 241
 242 Default: ``''`` (Empty string)
 243
 244 The password to use when connecting to the database. Not used with SQLite.
 245
 246 DATABASE_PORT
 247 -------------
 248
 249 Default: ``''`` (Empty string)
 250
 251 The port to use when connecting to the database. An empty string means the
 252 default port. Not used with SQLite.
 253
 254 DATABASE_USER
 255 -------------
 256
 257 Default: ``''`` (Empty string)
 258
 259 The username to use when connecting to the database. Not used with SQLite.
 260
 261 DATE_FORMAT
 262 -----------
 263
 264 Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``)
 265
 266 The default formatting to use for date fields on Django admin change-list
 267 pages -- and, possibly, by other parts of the system. See
 268 `allowed date format strings`_.
 269
 270 See also DATETIME_FORMAT and TIME_FORMAT.
 271
 272 .. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now
 273
 274 DATETIME_FORMAT
 275 ---------------
 276
 277 Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``)
 278
 279 The default formatting to use for datetime fields on Django admin change-list
 280 pages -- and, possibly, by other parts of the system. See
 281 `allowed date format strings`_.
 282
 283 See also DATE_FORMAT and TIME_FORMAT.
 284
 285 .. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now
 286
 287 DEBUG
 288 -----
 289
 290 Default: ``False``
 291
 292 A boolean that turns on/off debug mode.
 293
 294 DEFAULT_CHARSET
 295 ---------------
 296
 297 Default: ``'utf-8'``
 298
 299 Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't
 300 manually specified. Used with ``DEFAULT_CONTENT_TYPE`` to construct the
 301 ``Content-Type`` header.
 302
 303 DEFAULT_CONTENT_TYPE
 304 --------------------
 305
 306 Default: ``'text/html'``
 307
 308 Default content type to use for all ``HttpResponse`` objects, if a MIME type
 309 isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the
 310 ``Content-Type`` header.
 311
 312 DEFAULT_FROM_EMAIL
 313 ------------------
 314
 315 Default: ``'webmaster@localhost'``
 316
 317 Default e-mail address to use for various automated correspondence from the
 318 site manager(s).
 319
 320 DISALLOWED_USER_AGENTS
 321 ----------------------
 322
 323 Default: ``()`` (Empty tuple)
 324
 325 List of compiled regular expression objects representing User-Agent strings
 326 that are not allowed to visit any page, systemwide. Use this for bad
 327 robots/crawlers.  This is only used if ``CommonMiddleware`` is installed (see
 328 the `middleware docs`_).
 329
 330 EMAIL_HOST
 331 ----------
 332
 333 Default: ``'localhost'``
 334
 335 The host to use for sending e-mail.
 336
 337 EMAIL_SUBJECT_PREFIX
 338 --------------------
 339
 340 Default: ``'[Django] '``
 341
 342 Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins``
 343 or ``django.core.mail.mail_managers``. You'll probably want to include the
 344 trailing space.
 345
 346 IGNORABLE_404_ENDS
 347 ------------------
 348
 349 Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')``
 350
 351 See also ``IGNORABLE_404_STARTS``.
 352
 353 IGNORABLE_404_STARTS
 354 --------------------
 355
 356 Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')``
 357
 358 A tuple of strings that specify beginnings of URLs that should be ignored by
 359 the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS`` and ``IGNORABLE_404_ENDS``.
 360
 361 INSTALLED_APPS
 362 --------------
 363
 364 Default: ``()`` (Empty tuple)
 365
 366 A tuple of strings designating all applications that are enabled in this Django
 367 installation. Each string should be a full Python path to a Python package that
 368 contains a Django application, as created by `django-admin.py startapp`_.
 369
 370 .. _django-admin.py startapp: http://www.djangoproject.com/documentation/django_admin/#startapp-appname
 371
 372 INTERNAL_IPS
 373 ------------
 374
 375 Default: ``()`` (Empty tuple)
 376
 377 A tuple of IP addresses, as strings, that:
 378
 379     * See debug comments, when ``DEBUG`` is ``True``
 380     * Receive X headers if the ``XViewMiddleware`` is installed (see the
 381       `middleware docs`_)
 382
 383 JING_PATH
 384 ---------
 385
 386 Default: ``'/usr/bin/jing'``
 387
 388 Path to the "Jing" executable. Jing is a RELAX NG validator, and Django uses it
 389 to validate each ``XMLField`` in your models.
 390 See http://www.thaiopensource.com/relaxng/jing.html .
 391
 392 LANGUAGE_CODE
 393 -------------
 394
 395 Default: ``'en-us'``
 396
 397 A string representing the language code for this installation. This should be
 398 in standard language format. For example, U.S. English is ``"en-us"``. See the
 399 `internationalization docs`_.
 400
 401 .. _internationalization docs: http://www.djangoproject.com/documentation/i18n/
 402
 403 LANGUAGES
 404 ---------
 405
 406 Default: A tuple of all available languages. Currently, this is::
 407
 408     LANGUAGES = (
 409         ('bn', _('Bengali')),
 410         ('cs', _('Czech')),
 411         ('cy', _('Welsh')),
 412         ('da', _('Danish')),
 413         ('de', _('German')),
 414         ('en', _('English')),
 415         ('es', _('Spanish')),
 416         ('fr', _('French')),
 417         ('gl', _('Galician')),
 418         ('is', _('Icelandic')),
 419         ('it', _('Italian')),
 420         ('no', _('Norwegian')),
 421         ('pt-br', _('Brazilian')),
 422         ('ro', _('Romanian')),
 423         ('ru', _('Russian')),
 424         ('sk', _('Slovak')),
 425         ('sr', _('Serbian')),
 426         ('sv', _('Swedish')),
 427         ('zh-cn', _('Simplified Chinese')),
 428     )
 429
 430 A tuple of two-tuples in the format (language code, language name). This
 431 specifies which languages are available for language selection. See the
 432 `internationalization docs`_ for details.
 433
 434 Generally, the default value should suffice. Only set this setting if you want
 435 to restrict language selection to a subset of the Django-provided languages.
 436
 437 MANAGERS
 438 --------
 439
 440 Default: ``ADMINS`` (Whatever ``ADMINS`` is set to)
 441
 442 A tuple in the same format as ``ADMINS`` that specifies who should get
 443 broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``.
 444
 445 MEDIA_ROOT
 446 ----------
 447
 448 Default: ``''`` (Empty string)
 449
 450 Absolute path to the directory that holds media for this installation.
 451 Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``.
 452
 453 MEDIA_URL
 454 ---------
 455
 456 Default: ``''`` (Empty string)
 457
 458 URL that handles the media served from ``MEDIA_ROOT``.
 459 Example: ``"http://media.lawrence.com"``
 460
 461 MIDDLEWARE_CLASSES
 462 ------------------
 463
 464 Default::
 465
 466     ("django.middleware.sessions.SessionMiddleware",
 467      "django.middleware.common.CommonMiddleware",
 468      "django.middleware.doc.XViewMiddleware")
 469
 470 A tuple of middleware classes to use. See the `middleware docs`_.
 471
 472 PREPEND_WWW
 473 -----------
 474
 475 Default: ``False``
 476
 477 Whether to prepend the "www." subdomain to URLs that don't have it. This is
 478 only used if ``CommonMiddleware`` is installed (see the `middleware docs`_).
 479 See also ``APPEND_SLASH``.
 480
 481 SECRET_KEY
 482 ----------
 483
 484 Default: ``''`` (Empty string)
 485
 486 A secret key for this particular Django installation. Used to provide a seed in
 487 secret-key hashing algorithms. Set this to a random string -- the longer, the
 488 better. ``django-admin.py startproject`` creates one automatically.
 489
 490 SEND_BROKEN_LINK_EMAILS
 491 -----------------------
 492
 493 Default: ``False``
 494
 495 Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a
 496 Django-powered page that is 404ed with a non-empty referer (i.e., a broken
 497 link). This is only used if ``CommonMiddleware`` is installed (see the
 498 `middleware docs`_). See also ``IGNORABLE_404_STARTS`` and
 499 ``IGNORABLE_404_ENDS``.
 500
 501 SERVER_EMAIL
 502 ------------
 503
 504 Default: ``'root@localhost'``
 505
 506 The e-mail address that error messages come from, such as those sent to
 507 ``ADMINS`` and ``MANAGERS``.
 508
 509 SESSION_COOKIE_AGE
 510 ------------------
 511
 512 Default: ``1209600`` (2 weeks, in seconds)
 513
 514 The age of session cookies, in seconds. See the `session docs`_.
 515
 516 SESSION_COOKIE_DOMAIN
 517 ---------------------
 518
 519 Default: ``None``
 520
 521 The domain to use for session cookies. Set this to a string such as
 522 ``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard
 523 domain cookie. See the `session docs`_.
 524
 525 SESSION_COOKIE_NAME
 526 -------------------
 527
 528 Default: ``'hotclub'``
 529
 530 The name of the cookie to use for sessions. This can be whatever you want.
 531 See the `session docs`_.
 532
 533 ``'hotclub'`` is a reference to the Hot Club of France, the band Django
 534 Reinhardt played in.
 535
 536 SESSION_SAVE_EVERY_REQUEST
 537 --------------------------
 538
 539 Default: ``False``
 540
 541 Whether to save the session data on every request. See the `session docs`_.
 542
 543 SITE_ID
 544 -------
 545
 546 Default: Not defined
 547
 548 The ID, as an integer, of the current site in the ``sites`` database. This is
 549 used so that application data can hook into specific site(s) and a single
 550 database can manage content for multiple sites.
 551
 552 TEMPLATE_DEBUG
 553 --------------
 554
 555 Default: ``False``
 556
 557 **Only available in Django development version.**
 558
 559 A boolean that turns on/off template debug mode. If this is ``True``, the fancy
 560 error page will display a detailed report for any ``TemplateSyntaxError``. This
 561 report contains the relevant snippet of the template, with the appropriate line
 562 highlighted.
 563
 564 Note that Django only displays fancy error pages if ``DEBUG`` is ``True``, so you'll
 565 want to set that to take advantage of this setting.
 566
 567 See also DEBUG.
 568
 569 TEMPLATE_DIRS
 570 -------------
 571
 572 Default: ``()`` (Empty tuple)
 573
 574 List of locations of the template source files, in search order. See the
 575 `template documentation`_.
 576
 577 TEMPLATE_FILE_EXTENSION
 578 -----------------------
 579
 580 Default: ``'.html'``
 581
 582 The file extension to append to all template names when searching for
 583 templates. See the `template documentation`_.
 584
 585 TEMPLATE_LOADERS
 586 ----------------
 587
 588 Default: ``('django.core.template.loaders.filesystem.load_template_source',)``
 589
 590 A tuple of callables (as strings) that know how to import templates from
 591 various sources. See the `template documentation`_.
 592
 593 TIME_FORMAT
 594 -----------
 595
 596 Default: ``'P'`` (e.g. ``4 p.m.``)
 597
 598 The default formatting to use for time fields on Django admin change-list
 599 pages -- and, possibly, by other parts of the system. See
 600 `allowed date format strings`_.
 601
 602 See also DATE_FORMAT and DATETIME_FORMAT.
 603
 604 .. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now
 605
 606 TIME_ZONE
 607 ---------
 608
 609 Default: ``'America/Chicago'``
 610
 611 A string representing the time zone for this installation. `See available choices`_.
 612
 613 Note that this is the time zone to which Django will convert all dates/times --
 614 not necessarily the timezone of the server. For example, one server may serve
 615 multiple Django-powered sites, each with a separate time-zone setting.
 616
 617 USE_ETAGS
 618 ---------
 619
 620 Default: ``False``
 621
 622 A boolean that specifies whether to output the "Etag" header. This saves
 623 bandwidth but slows down performance. This is only used if ``CommonMiddleware``
 624 is installed (see the `middleware docs`_).
 625
 626 .. _cache docs: http://www.djangoproject.com/documentation/cache/
 627 .. _middleware docs: http://www.djangoproject.com/documentation/middleware/
 628 .. _session docs: http://www.djangoproject.com/documentation/sessions/
 629 .. _See available choices: http://www.postgresql.org/docs/current/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
 630 .. _template documentation: http://www.djangoproject.com/documentation/templates_python/
 631
 632 Creating your own settings
 633 ==========================
 634
 635 There's nothing stopping you from creating your own settings, for your own
 636 Django apps. Just follow these conventions:
 637
 638     * Setting names are in all uppercase.
 639     * For settings that are sequences, use tuples instead of lists. This is
 640       purely for performance.
 641     * Don't reinvent an already-existing setting.