Debian Codegraph @

docs/ref/settings.txt

raw
1 ========
2 Settings
3 ========
4
5 .. contents::
6 :local:
7 :depth: 1
8
9 .. warning::
10
11 Be careful when you override settings, especially when the default value
12 is a non-empty list or dictionary, such as :setting:`STATICFILES_FINDERS`.
13 Make sure you keep the components required by the features of Django you
14 wish to use.
15
16 Core Settings
17 =============
18
19 Here's a list of settings available in Django core and their default values.
20 Settings provided by contrib apps are listed below, followed by a topical index
21 of the core settings. For introductory material, see the :doc:`settings topic
22 guide </topics/settings>`.
23
24 .. setting:: ABSOLUTE_URL_OVERRIDES
25
26 ``ABSOLUTE_URL_OVERRIDES``
27 --------------------------
28
29 Default: ``{}`` (Empty dictionary)
30
31 A dictionary mapping ``"app_label.model_name"`` strings to functions that take
32 a model object and return its URL. This is a way of inserting or overriding
33 ``get_absolute_url()`` methods on a per-installation basis. Example::
34
35 ABSOLUTE_URL_OVERRIDES = {
36 "blogs.blog": lambda o: "/blogs/%s/" % o.slug,
37 "news.story": lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
38 }
39
40 The model name used in this setting should be all lowercase, regardless of the
41 case of the actual model class name.
42
43 .. setting:: ADMINS
44
45 ``ADMINS``
46 ----------
47
48 Default: ``[]`` (Empty list)
49
50 A list of all the people who get code error notifications. When
51 :setting:`DEBUG=False <DEBUG>` and :class:`~django.utils.log.AdminEmailHandler`
52 is configured in :setting:`LOGGING` (done by default), Django emails these
53 people the details of exceptions raised in the request/response cycle.
54
55 Each item in the list should be a tuple of (Full name, email address). Example::
56
57 [("John", "[email protected]"), ("Mary", "[email protected]")]
58
59 .. setting:: ALLOWED_HOSTS
60
61 ``ALLOWED_HOSTS``
62 -----------------
63
64 Default: ``[]`` (Empty list)
65
66 A list of strings representing the host/domain names that this Django site can
67 serve. This is a security measure to prevent :ref:`HTTP Host header attacks
68 <host-headers-virtual-hosting>`, which are possible even under many
69 seemingly-safe web server configurations.
70
71 Values in this list can be fully qualified names (e.g. ``'www.example.com'``),
72 in which case they will be matched against the request's ``Host`` header
73 exactly (case-insensitive, not including port). A value beginning with a period
74 can be used as a subdomain wildcard: ``'.example.com'`` will match
75 ``example.com``, ``www.example.com``, and any other subdomain of
76 ``example.com``. A value of ``'*'`` will match anything; in this case you are
77 responsible to provide your own validation of the ``Host`` header (perhaps in a
78 middleware; if so this middleware must be listed first in
79 :setting:`MIDDLEWARE`).
80
81 Django also allows the `fully qualified domain name (FQDN)`_ of any entries.
82 Some browsers include a trailing dot in the ``Host`` header which Django
83 strips when performing host validation.
84
85 .. _`fully qualified domain name (FQDN)`: https://en.wikipedia.org/wiki/Fully_qualified_domain_name
86
87 If the ``Host`` header (or ``X-Forwarded-Host`` if
88 :setting:`USE_X_FORWARDED_HOST` is enabled) does not match any value in this
89 list, the :meth:`django.http.HttpRequest.get_host()` method will raise
90 :exc:`~django.core.exceptions.SuspiciousOperation`.
91
92 When :setting:`DEBUG` is ``True`` and ``ALLOWED_HOSTS`` is empty, the host
93 is validated against ``['.localhost', '127.0.0.1', '[::1]']``.
94
95 ``ALLOWED_HOSTS`` is also :ref:`checked when running tests
96 <topics-testing-advanced-multiple-hosts>`.
97
98 This validation only applies via :meth:`~django.http.HttpRequest.get_host()`;
99 if your code accesses the ``Host`` header directly from ``request.META`` you
100 are bypassing this security protection.
101
102 .. setting:: APPEND_SLASH
103
104 ``APPEND_SLASH``
105 ----------------
106
107 Default: ``True``
108
109 When set to ``True``, if the request URL does not match any of the patterns
110 in the URLconf and it doesn't end in a slash, an HTTP redirect is issued to the
111 same URL with a slash appended. Note that the redirect may cause any data
112 submitted in a POST request to be lost.
113
114 The :setting:`APPEND_SLASH` setting is only used if
115 :class:`~django.middleware.common.CommonMiddleware` is installed
116 (see :doc:`/topics/http/middleware`). See also :setting:`PREPEND_WWW`.
117
118 .. setting:: CACHES
119
120 ``CACHES``
121 ----------
122
123 Default::
124
125 {
126 "default": {
127 "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
128 }
129 }
130
131 A dictionary containing the settings for all caches to be used with
132 Django. It is a nested dictionary whose contents maps cache aliases
133 to a dictionary containing the options for an individual cache.
134
135 The :setting:`CACHES` setting must configure a ``default`` cache;
136 any number of additional caches may also be specified. If you
137 are using a cache backend other than the local memory cache, or
138 you need to define multiple caches, other options will be required.
139 The following cache options are available.
140
141 .. setting:: CACHES-BACKEND
142
143 ``BACKEND``
144 ~~~~~~~~~~~
145
146 Default: ``''`` (Empty string)
147
148 The cache backend to use. The built-in cache backends are:
149
150 * ``'django.core.cache.backends.db.DatabaseCache'``
151 * ``'django.core.cache.backends.dummy.DummyCache'``
152 * ``'django.core.cache.backends.filebased.FileBasedCache'``
153 * ``'django.core.cache.backends.locmem.LocMemCache'``
154 * ``'django.core.cache.backends.memcached.PyMemcacheCache'``
155 * ``'django.core.cache.backends.memcached.PyLibMCCache'``
156 * ``'django.core.cache.backends.redis.RedisCache'``
157
158 You can use a cache backend that doesn't ship with Django by setting
159 :setting:`BACKEND <CACHES-BACKEND>` to a fully-qualified path of a cache
160 backend class (i.e. ``mypackage.backends.whatever.WhateverCache``).
161
162 .. setting:: CACHES-KEY_FUNCTION
163
164 ``KEY_FUNCTION``
165 ~~~~~~~~~~~~~~~~
166
167 A string containing a dotted path to a function (or any callable) that defines how to
168 compose a prefix, version and key into a final cache key. The default
169 implementation is equivalent to the function::
170
171 def make_key(key, key_prefix, version):
172 return ":".join([key_prefix, str(version), key])
173
174 You may use any key function you want, as long as it has the same
175 argument signature.
176
177 See the :ref:`cache documentation <cache_key_transformation>` for more
178 information.
179
180 .. setting:: CACHES-KEY_PREFIX
181
182 ``KEY_PREFIX``
183 ~~~~~~~~~~~~~~
184
185 Default: ``''`` (Empty string)
186
187 A string that will be automatically included (prepended by default) to
188 all cache keys used by the Django server.
189
190 See the :ref:`cache documentation <cache_key_prefixing>` for more information.
191
192 .. setting:: CACHES-LOCATION
193
194 ``LOCATION``
195 ~~~~~~~~~~~~
196
197 Default: ``''`` (Empty string)
198
199 The location of the cache to use. This might be the directory for a
200 file system cache, a host and port for a memcache server, or an identifying
201 name for a local memory cache. e.g.::
202
203 CACHES = {
204 "default": {
205 "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
206 "LOCATION": "/var/tmp/django_cache",
207 }
208 }
209
210 .. setting:: CACHES-OPTIONS
211
212 ``OPTIONS``
213 ~~~~~~~~~~~
214
215 Default: ``None``
216
217 Extra parameters to pass to the cache backend. Available parameters
218 vary depending on your cache backend.
219
220 Some information on available parameters can be found in the
221 :ref:`cache arguments <cache_arguments>` documentation. For more information,
222 consult your backend module's own documentation.
223
224 .. setting:: CACHES-TIMEOUT
225
226 ``TIMEOUT``
227 ~~~~~~~~~~~
228
229 Default: ``300``
230
231 The number of seconds before a cache entry is considered stale. If the value of
232 this setting is ``None``, cache entries will not expire. A value of ``0``
233 causes keys to immediately expire (effectively "don't cache").
234
235 .. setting:: CACHES-VERSION
236
237 ``VERSION``
238 ~~~~~~~~~~~
239
240 Default: ``1``
241
242 The default version number for cache keys generated by the Django server.
243
244 See the :ref:`cache documentation <cache_versioning>` for more information.
245
246 .. setting:: CACHE_MIDDLEWARE_ALIAS
247
248 ``CACHE_MIDDLEWARE_ALIAS``
249 --------------------------
250
251 Default: ``'default'``
252
253 The cache connection to use for the :ref:`cache middleware
254 <the-per-site-cache>`.
255
256 .. setting:: CACHE_MIDDLEWARE_KEY_PREFIX
257
258 ``CACHE_MIDDLEWARE_KEY_PREFIX``
259 -------------------------------
260
261 Default: ``''`` (Empty string)
262
263 A string which will be prefixed to the cache keys generated by the :ref:`cache
264 middleware <the-per-site-cache>`. This prefix is combined with the
265 :setting:`KEY_PREFIX <CACHES-KEY_PREFIX>` setting; it does not replace it.
266
267 See :doc:`/topics/cache`.
268
269 .. setting:: CACHE_MIDDLEWARE_SECONDS
270
271 ``CACHE_MIDDLEWARE_SECONDS``
272 ----------------------------
273
274 Default: ``600``
275
276 The default integer number of seconds to cache a page for the
277 :ref:`cache middleware <the-per-site-cache>`.
278
279 See :doc:`/topics/cache`.
280
281 .. _settings-csrf:
282
283 .. setting:: CSRF_COOKIE_AGE
284
285 ``CSRF_COOKIE_AGE``
286 -------------------
287
288 Default: ``31449600`` (approximately 1 year, in seconds)
289
290 The age of CSRF cookies, in seconds.
291
292 The reason for setting a long-lived expiration time is to avoid problems in
293 the case of a user closing a browser or bookmarking a page and then loading
294 that page from a browser cache. Without persistent cookies, the form submission
295 would fail in this case.
296
297 Some browsers (specifically Internet Explorer) can disallow the use of
298 persistent cookies or can have the indexes to the cookie jar corrupted on disk,
299 thereby causing CSRF protection checks to (sometimes intermittently) fail.
300 Change this setting to ``None`` to use session-based CSRF cookies, which
301 keep the cookies in-memory instead of on persistent storage.
302
303 .. setting:: CSRF_COOKIE_DOMAIN
304
305 ``CSRF_COOKIE_DOMAIN``
306 ----------------------
307
308 Default: ``None``
309
310 The domain to be used when setting the CSRF cookie. This can be useful for
311 easily allowing cross-subdomain requests to be excluded from the normal cross
312 site request forgery protection. It should be set to a string such as
313 ``".example.com"`` to allow a POST request from a form on one subdomain to be
314 accepted by a view served from another subdomain.
315
316 Please note that the presence of this setting does not imply that Django's CSRF
317 protection is safe from cross-subdomain attacks by default - please see the
318 :ref:`CSRF limitations <csrf-limitations>` section.
319
320 .. setting:: CSRF_COOKIE_HTTPONLY
321
322 ``CSRF_COOKIE_HTTPONLY``
323 ------------------------
324
325 Default: ``False``
326
327 Whether to use ``HttpOnly`` flag on the CSRF cookie. If this is set to
328 ``True``, client-side JavaScript will not be able to access the CSRF cookie.
329
330 Designating the CSRF cookie as ``HttpOnly`` doesn't offer any practical
331 protection because CSRF is only to protect against cross-domain attacks. If an
332 attacker can read the cookie via JavaScript, they're already on the same domain
333 as far as the browser knows, so they can do anything they like anyway. (XSS is
334 a much bigger hole than CSRF.)
335
336 Although the setting offers little practical benefit, it's sometimes required
337 by security auditors.
338
339 If you enable this and need to send the value of the CSRF token with an AJAX
340 request, your JavaScript must pull the value :ref:`from a hidden CSRF token
341 form input <acquiring-csrf-token-from-html>` instead of :ref:`from the cookie
342 <acquiring-csrf-token-from-cookie>`.
343
344 See :setting:`SESSION_COOKIE_HTTPONLY` for details on ``HttpOnly``.
345
346 .. setting:: CSRF_COOKIE_NAME
347
348 ``CSRF_COOKIE_NAME``
349 --------------------
350
351 Default: ``'csrftoken'``
352
353 The name of the cookie to use for the CSRF authentication token. This can be
354 whatever you want (as long as it's different from the other cookie names in
355 your application). See :doc:`/ref/csrf`.
356
357 .. setting:: CSRF_COOKIE_PATH
358
359 ``CSRF_COOKIE_PATH``
360 --------------------
361
362 Default: ``'/'``
363
364 The path set on the CSRF cookie. This should either match the URL path of your
365 Django installation or be a parent of that path.
366
367 This is useful if you have multiple Django instances running under the same
368 hostname. They can use different cookie paths, and each instance will only see
369 its own CSRF cookie.
370
371 .. setting:: CSRF_COOKIE_SAMESITE
372
373 ``CSRF_COOKIE_SAMESITE``
374 ------------------------
375
376 Default: ``'Lax'``
377
378 The value of the `SameSite`_ flag on the CSRF cookie. This flag prevents the
379 cookie from being sent in cross-site requests.
380
381 See :setting:`SESSION_COOKIE_SAMESITE` for details about ``SameSite``.
382
383 .. setting:: CSRF_COOKIE_SECURE
384
385 ``CSRF_COOKIE_SECURE``
386 ----------------------
387
388 Default: ``False``
389
390 Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``,
391 the cookie will be marked as "secure", which means browsers may ensure that the
392 cookie is only sent with an HTTPS connection.
393
394 .. setting:: CSRF_USE_SESSIONS
395
396 ``CSRF_USE_SESSIONS``
397 ---------------------
398
399 Default: ``False``
400
401 Whether to store the CSRF token in the user's session instead of in a cookie.
402 It requires the use of :mod:`django.contrib.sessions`.
403
404 Storing the CSRF token in a cookie (Django's default) is safe, but storing it
405 in the session is common practice in other web frameworks and therefore
406 sometimes demanded by security auditors.
407
408 Since the :ref:`default error views <error-views>` require the CSRF token,
409 :class:`~django.contrib.sessions.middleware.SessionMiddleware` must appear in
410 :setting:`MIDDLEWARE` before any middleware that may raise an exception to
411 trigger an error view (such as :exc:`~django.core.exceptions.PermissionDenied`)
412 if you're using ``CSRF_USE_SESSIONS``. See :ref:`middleware-ordering`.
413
414 .. setting:: CSRF_FAILURE_VIEW
415
416 ``CSRF_FAILURE_VIEW``
417 ---------------------
418
419 Default: ``'django.views.csrf.csrf_failure'``
420
421 A dotted path to the view function to be used when an incoming request is
422 rejected by the :doc:`CSRF protection </ref/csrf>`. The function should have
423 this signature::
424
425 def csrf_failure(request, reason=""): ...
426
427 where ``reason`` is a short message (intended for developers or logging, not
428 for end users) indicating the reason the request was rejected. It should return
429 an :class:`~django.http.HttpResponseForbidden`.
430
431 ``django.views.csrf.csrf_failure()`` accepts an additional ``template_name``
432 parameter that defaults to ``'403_csrf.html'``. If a template with that name
433 exists, it will be used to render the page.
434
435 .. setting:: CSRF_HEADER_NAME
436
437 ``CSRF_HEADER_NAME``
438 --------------------
439
440 Default: ``'HTTP_X_CSRFTOKEN'``
441
442 The name of the request header used for CSRF authentication.
443
444 As with other HTTP headers in ``request.META``, the header name received from
445 the server is normalized by converting all characters to uppercase, replacing
446 any hyphens with underscores, and adding an ``'HTTP_'`` prefix to the name.
447 For example, if your client sends a ``'X-XSRF-TOKEN'`` header, the setting
448 should be ``'HTTP_X_XSRF_TOKEN'``.
449
450 .. setting:: CSRF_TRUSTED_ORIGINS
451
452 ``CSRF_TRUSTED_ORIGINS``
453 ------------------------
454
455 Default: ``[]`` (Empty list)
456
457 A list of trusted origins for unsafe requests (e.g. ``POST``).
458
459 For requests that include the ``Origin`` header, Django's CSRF protection
460 requires that header match the origin present in the ``Host`` header.
461
462 For a :meth:`secure <django.http.HttpRequest.is_secure>` unsafe
463 request that doesn't include the ``Origin`` header, the request must have a
464 ``Referer`` header that matches the origin present in the ``Host`` header.
465
466 These checks prevent, for example, a ``POST`` request from
467 ``subdomain.example.com`` from succeeding against ``api.example.com``. If you
468 need cross-origin unsafe requests, continuing the example, add
469 ``'https://subdomain.example.com'`` to this list (and/or ``http://...`` if
470 requests originate from an insecure page).
471
472 The setting also supports subdomains, so you could add
473 ``'https://*.example.com'``, for example, to allow access from all subdomains
474 of ``example.com``.
475
476 .. setting:: DATABASES
477
478 ``DATABASES``
479 -------------
480
481 Default: ``{}`` (Empty dictionary)
482
483 A dictionary containing the settings for all databases to be used with
484 Django. It is a nested dictionary whose contents map a database alias
485 to a dictionary containing the options for an individual database.
486
487 The :setting:`DATABASES` setting must configure a ``default`` database;
488 any number of additional databases may also be specified.
489
490 The simplest possible settings file is for a single-database setup using
491 SQLite. This can be configured using the following::
492
493 DATABASES = {
494 "default": {
495 "ENGINE": "django.db.backends.sqlite3",
496 "NAME": "mydatabase",
497 }
498 }
499
500 When connecting to other database backends, such as MariaDB, MySQL, Oracle, or
501 PostgreSQL, additional connection parameters will be required. See
502 the :setting:`ENGINE <DATABASE-ENGINE>` setting below on how to specify
503 other database types. This example is for PostgreSQL::
504
505 DATABASES = {
506 "default": {
507 "ENGINE": "django.db.backends.postgresql",
508 "NAME": "mydatabase",
509 "USER": "mydatabaseuser",
510 "PASSWORD": "mypassword",
511 "HOST": "127.0.0.1",
512 "PORT": "5432",
513 }
514 }
515
516 The following inner options that may be required for more complex
517 configurations are available:
518
519 .. setting:: DATABASE-ATOMIC_REQUESTS
520
521 ``ATOMIC_REQUESTS``
522 ~~~~~~~~~~~~~~~~~~~
523
524 Default: ``False``
525
526 Set this to ``True`` to wrap each view in a transaction on this database. See
527 :ref:`tying-transactions-to-http-requests`.
528
529 .. setting:: DATABASE-AUTOCOMMIT
530
531 ``AUTOCOMMIT``
532 ~~~~~~~~~~~~~~
533
534 Default: ``True``
535
536 Set this to ``False`` if you want to :ref:`disable Django's transaction
537 management <deactivate-transaction-management>` and implement your own.
538
539 .. setting:: DATABASE-ENGINE
540
541 ``ENGINE``
542 ~~~~~~~~~~
543
544 Default: ``''`` (Empty string)
545
546 The database backend to use. The built-in database backends are:
547
548 * ``'django.db.backends.postgresql'``
549 * ``'django.db.backends.mysql'``
550 * ``'django.db.backends.sqlite3'``
551 * ``'django.db.backends.oracle'``
552
553 You can use a database backend that doesn't ship with Django by setting
554 ``ENGINE`` to a fully-qualified path (i.e. ``mypackage.backends.whatever``).
555
556 .. setting:: HOST
557
558 ``HOST``
559 ~~~~~~~~
560
561 Default: ``''`` (Empty string)
562
563 Which host to use when connecting to the database. An empty string means
564 localhost. Not used with SQLite.
565
566 If this value starts with a forward slash (``'/'``) and you're using MySQL,
567 MySQL will connect via a Unix socket to the specified socket. For example::
568
569 "HOST": "/var/run/mysql"
570
571 If you're using MySQL and this value *doesn't* start with a forward slash, then
572 this value is assumed to be the host.
573
574 If you're using PostgreSQL, by default (empty :setting:`HOST`), the connection
575 to the database is done through UNIX domain sockets ('local' lines in
576 ``pg_hba.conf``). If your UNIX domain socket is not in the standard location,
577 use the same value of ``unix_socket_directory`` from ``postgresql.conf``.
578 If you want to connect through TCP sockets, set :setting:`HOST` to 'localhost'
579 or '127.0.0.1' ('host' lines in ``pg_hba.conf``).
580 On Windows, you should always define :setting:`HOST`, as UNIX domain sockets
581 are not available.
582
583 .. setting:: NAME
584
585 ``NAME``
586 ~~~~~~~~
587
588 Default: ``''`` (Empty string)
589
590 The name of the database to use. For SQLite, it's the full path to the database
591 file. When specifying the path, always use forward slashes, even on Windows
592 (e.g. ``C:/homes/user/mysite/sqlite3.db``).
593
594 .. setting:: CONN_MAX_AGE
595
596 ``CONN_MAX_AGE``
597 ~~~~~~~~~~~~~~~~
598
599 Default: ``0``
600
601 The lifetime of a database connection, as an integer of seconds. Use ``0`` to
602 close database connections at the end of each request — Django's historical
603 behavior — and ``None`` for unlimited :ref:`persistent database connections
604 <persistent-database-connections>`.
605
606 .. setting:: CONN_HEALTH_CHECKS
607
608 ``CONN_HEALTH_CHECKS``
609 ~~~~~~~~~~~~~~~~~~~~~~
610
611 Default: ``False``
612
613 If set to ``True``, existing :ref:`persistent database connections
614 <persistent-database-connections>` will be health checked before they are
615 reused in each request performing database access. If the health check fails,
616 the connection will be reestablished without failing the request when the
617 connection is no longer usable but the database server is ready to accept and
618 serve new connections (e.g. after database server restart closing existing
619 connections).
620
621 .. setting:: OPTIONS
622
623 ``OPTIONS``
624 ~~~~~~~~~~~
625
626 Default: ``{}`` (Empty dictionary)
627
628 Extra parameters to use when connecting to the database. Available parameters
629 vary depending on your database backend.
630
631 Some information on available parameters can be found in the
632 :doc:`Database Backends </ref/databases>` documentation. For more information,
633 consult your backend module's own documentation.
634
635 .. setting:: PASSWORD
636
637 ``PASSWORD``
638 ~~~~~~~~~~~~
639
640 Default: ``''`` (Empty string)
641
642 The password to use when connecting to the database. Not used with SQLite.
643
644 .. setting:: PORT
645
646 ``PORT``
647 ~~~~~~~~
648
649 Default: ``''`` (Empty string)
650
651 The port to use when connecting to the database. An empty string means the
652 default port. Not used with SQLite.
653
654 .. setting:: DATABASE-TIME_ZONE
655
656 ``TIME_ZONE``
657 ~~~~~~~~~~~~~
658
659 Default: ``None``
660
661 A string representing the time zone for this database connection or ``None``.
662 This inner option of the :setting:`DATABASES` setting accepts the same values
663 as the general :setting:`TIME_ZONE` setting.
664
665 When :setting:`USE_TZ` is ``True``, reading datetimes from the database
666 returns aware datetimes with the timezone set to this option's value if not
667 ``None``, or to UTC otherwise.
668
669 When :setting:`USE_TZ` is ``False``, it is an error to set this option.
670
671 * If the database backend doesn't support time zones (e.g. SQLite, MySQL,
672 Oracle), Django reads and writes datetimes in local time according to this
673 option if it is set and in UTC if it isn't.
674
675 Changing the connection time zone changes how datetimes are read from and
676 written to the database.
677
678 * If Django manages the database and you don't have a strong reason to do
679 otherwise, you should leave this option unset. It's best to store datetimes
680 in UTC because it avoids ambiguous or nonexistent datetimes during daylight
681 saving time changes. Also, receiving datetimes in UTC keeps datetime
682 arithmetic simple — there's no need to consider potential offset changes
683 over a DST transition.
684
685 * If you're connecting to a third-party database that stores datetimes in a
686 local time rather than UTC, then you must set this option to the
687 appropriate time zone. Likewise, if Django manages the database but
688 third-party systems connect to the same database and expect to find
689 datetimes in local time, then you must set this option.
690
691 * If the database backend supports time zones (e.g., PostgreSQL), then the
692 database connection's time zone is set to this value.
693
694 Although setting the ``TIME_ZONE`` option is very rarely needed, there are
695 situations where it becomes necessary. Specifically, it's recommended to
696 match the general :setting:`TIME_ZONE` setting when dealing with raw queries
697 involving date/time functions like PostgreSQL's ``date_trunc()`` or
698 ``generate_series()``, especially when generating time-based series that
699 transition daylight savings.
700
701 This value can be changed at any time, the database will handle the
702 conversion of datetimes to the configured time zone.
703
704 However, this has a downside: receiving all datetimes in local time makes
705 datetime arithmetic more tricky — you must account for possible offset
706 changes over DST transitions.
707
708 Consider converting to local time explicitly with ``AT TIME ZONE`` in raw SQL
709 queries instead of setting the ``TIME_ZONE`` option.
710
711 .. setting:: DATABASE-DISABLE_SERVER_SIDE_CURSORS
712
713 ``DISABLE_SERVER_SIDE_CURSORS``
714 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
715
716 Default: ``False``
717
718 Set this to ``True`` if you want to disable the use of server-side cursors with
719 :meth:`.QuerySet.iterator`. :ref:`transaction-pooling-server-side-cursors`
720 describes the use case.
721
722 This is a PostgreSQL-specific setting.
723
724 .. setting:: USER
725
726 ``USER``
727 ~~~~~~~~
728
729 Default: ``''`` (Empty string)
730
731 The username to use when connecting to the database. Not used with SQLite.
732
733 .. setting:: DATABASE-TEST
734
735 ``TEST``
736 ~~~~~~~~
737
738 Default: ``{}`` (Empty dictionary)
739
740 A dictionary of settings for test databases; for more details about the
741 creation and use of test databases, see :ref:`the-test-database`.
742
743 Here's an example with a test database configuration::
744
745 DATABASES = {
746 "default": {
747 "ENGINE": "django.db.backends.postgresql",
748 "USER": "mydatabaseuser",
749 "NAME": "mydatabase",
750 "TEST": {
751 "NAME": "mytestdatabase",
752 },
753 },
754 }
755
756 The following keys in the ``TEST`` dictionary are available:
757
758 .. setting:: TEST_CHARSET
759
760 ``CHARSET``
761 ^^^^^^^^^^^
762
763 Default: ``None``
764
765 The character set encoding used to create the test database. The value of this
766 string is passed directly through to the database, so its format is
767 backend-specific.
768
769 Supported by the PostgreSQL_ (``postgresql``) and MySQL_ (``mysql``) backends.
770
771 .. _PostgreSQL: https://www.postgresql.org/docs/current/multibyte.html
772 .. _MySQL: https://dev.mysql.com/doc/refman/en/charset-charsets.html
773
774 .. setting:: TEST_COLLATION
775
776 ``COLLATION``
777 ^^^^^^^^^^^^^
778
779 Default: ``None``
780
781 The collation order to use when creating the test database. This value is
782 passed directly to the backend, so its format is backend-specific.
783
784 Only supported for the ``mysql`` backend (see the `MySQL manual`_ for details).
785
786 .. _MySQL manual: MySQL_
787
788 .. setting:: TEST_DEPENDENCIES
789
790 ``DEPENDENCIES``
791 ^^^^^^^^^^^^^^^^
792
793 Default: ``['default']``, for all databases other than ``default``,
794 which has no dependencies.
795
796 The creation-order dependencies of the database. See the documentation
797 on :ref:`controlling the creation order of test databases
798 <topics-testing-creation-dependencies>` for details.
799
800 .. setting:: TEST_MIGRATE
801
802 ``MIGRATE``
803 ^^^^^^^^^^^
804
805 Default: ``True``
806
807 When set to ``False``, migrations won't run when creating the test database.
808 This is similar to setting ``None`` as a value in :setting:`MIGRATION_MODULES`,
809 but for all apps.
810
811 .. setting:: TEST_MIRROR
812
813 ``MIRROR``
814 ^^^^^^^^^^
815
816 Default: ``None``
817
818 The alias of the database that this database should mirror during
819 testing. It depends on transactions and therefore must be used within
820 :class:`~django.test.TransactionTestCase` instead of
821 :class:`~django.test.TestCase`.
822
823 This setting exists to allow for testing of primary/replica
824 (referred to as master/slave by some databases)
825 configurations of multiple databases. See the documentation on
826 :ref:`testing primary/replica configurations
827 <topics-testing-primaryreplica>` for details.
828
829 .. setting:: TEST_NAME
830
831 ``NAME``
832 ^^^^^^^^
833
834 Default: ``None``
835
836 The name of database to use when running the test suite.
837
838 If the default value (``None``) is used with the SQLite database engine, the
839 tests will use a memory resident database. For all other database engines the
840 test database will use the name ``'test_' + DATABASE_NAME``.
841
842 See :ref:`the-test-database`.
843
844 .. setting:: TEST_TEMPLATE
845
846 ``TEMPLATE``
847 ^^^^^^^^^^^^
848
849 This is a PostgreSQL-specific setting.
850
851 The name of a `template`_ (e.g. ``'template0'``) from which to create the test
852 database.
853
854 .. _template: https://www.postgresql.org/docs/current/sql-createdatabase.html
855
856 .. setting:: TEST_CREATE
857
858 ``CREATE_DB``
859 ^^^^^^^^^^^^^
860
861 Default: ``True``
862
863 This is an Oracle-specific setting.
864
865 If it is set to ``False``, the test tablespaces won't be automatically created
866 at the beginning of the tests or dropped at the end.
867
868 .. setting:: TEST_USER_CREATE
869
870 ``CREATE_USER``
871 ^^^^^^^^^^^^^^^
872
873 Default: ``True``
874
875 This is an Oracle-specific setting.
876
877 If it is set to ``False``, the test user won't be automatically created at the
878 beginning of the tests and dropped at the end.
879
880 .. setting:: TEST_USER
881
882 ``USER``
883 ^^^^^^^^
884
885 Default: ``None``
886
887 This is an Oracle-specific setting.
888
889 The username to use when connecting to the Oracle database that will be used
890 when running tests. If not provided, Django will use ``'test_' + USER``.
891
892 .. setting:: TEST_PASSWD
893
894 ``PASSWORD``
895 ^^^^^^^^^^^^
896
897 Default: ``None``
898
899 This is an Oracle-specific setting.
900
901 The password to use when connecting to the Oracle database that will be used
902 when running tests. If not provided, Django will generate a random password.
903
904 .. setting:: TEST_ORACLE_MANAGED_FILES
905
906 ``ORACLE_MANAGED_FILES``
907 ^^^^^^^^^^^^^^^^^^^^^^^^
908
909 Default: ``False``
910
911 This is an Oracle-specific setting.
912
913 If set to ``True``, Oracle Managed Files (OMF) tablespaces will be used.
914 :setting:`DATAFILE` and :setting:`DATAFILE_TMP` will be ignored.
915
916 .. setting:: TEST_TBLSPACE
917
918 ``TBLSPACE``
919 ^^^^^^^^^^^^
920
921 Default: ``None``
922
923 This is an Oracle-specific setting.
924
925 The name of the tablespace that will be used when running tests. If not
926 provided, Django will use ``'test_' + USER``.
927
928 .. setting:: TEST_TBLSPACE_TMP
929
930 ``TBLSPACE_TMP``
931 ^^^^^^^^^^^^^^^^
932
933 Default: ``None``
934
935 This is an Oracle-specific setting.
936
937 The name of the temporary tablespace that will be used when running tests. If
938 not provided, Django will use ``'test_' + USER + '_temp'``.
939
940 .. setting:: DATAFILE
941
942 ``DATAFILE``
943 ^^^^^^^^^^^^
944
945 Default: ``None``
946
947 This is an Oracle-specific setting.
948
949 The name of the datafile to use for the TBLSPACE. If not provided, Django will
950 use ``TBLSPACE + '.dbf'``.
951
952 .. setting:: DATAFILE_TMP
953
954 ``DATAFILE_TMP``
955 ^^^^^^^^^^^^^^^^
956
957 Default: ``None``
958
959 This is an Oracle-specific setting.
960
961 The name of the datafile to use for the TBLSPACE_TMP. If not provided, Django
962 will use ``TBLSPACE_TMP + '.dbf'``.
963
964 .. setting:: DATAFILE_MAXSIZE
965
966 ``DATAFILE_MAXSIZE``
967 ^^^^^^^^^^^^^^^^^^^^
968
969 Default: ``'500M'``
970
971 This is an Oracle-specific setting.
972
973 The maximum size that the DATAFILE is allowed to grow to.
974
975 .. setting:: DATAFILE_TMP_MAXSIZE
976
977 ``DATAFILE_TMP_MAXSIZE``
978 ^^^^^^^^^^^^^^^^^^^^^^^^
979
980 Default: ``'500M'``
981
982 This is an Oracle-specific setting.
983
984 The maximum size that the DATAFILE_TMP is allowed to grow to.
985
986 .. setting:: DATAFILE_SIZE
987
988 ``DATAFILE_SIZE``
989 ^^^^^^^^^^^^^^^^^
990
991 Default: ``'50M'``
992
993 This is an Oracle-specific setting.
994
995 The initial size of the DATAFILE.
996
997 .. setting:: DATAFILE_TMP_SIZE
998
999 ``DATAFILE_TMP_SIZE``
1000 ^^^^^^^^^^^^^^^^^^^^^
1001
1002 Default: ``'50M'``
1003
1004 This is an Oracle-specific setting.
1005
1006 The initial size of the DATAFILE_TMP.
1007
1008 .. setting:: DATAFILE_EXTSIZE
1009
1010 ``DATAFILE_EXTSIZE``
1011 ^^^^^^^^^^^^^^^^^^^^
1012
1013 Default: ``'25M'``
1014
1015 This is an Oracle-specific setting.
1016
1017 The amount by which the DATAFILE is extended when more space is required.
1018
1019 .. setting:: DATAFILE_TMP_EXTSIZE
1020
1021 ``DATAFILE_TMP_EXTSIZE``
1022 ^^^^^^^^^^^^^^^^^^^^^^^^
1023
1024 Default: ``'25M'``
1025
1026 This is an Oracle-specific setting.
1027
1028 The amount by which the DATAFILE_TMP is extended when more space is required.
1029
1030 .. setting:: DATA_UPLOAD_MAX_MEMORY_SIZE
1031
1032 ``DATA_UPLOAD_MAX_MEMORY_SIZE``
1033 -------------------------------
1034
1035 Default: ``2621440`` (i.e. 2.5 MB).
1036
1037 The maximum size in bytes that a request body may be before a
1038 :exc:`~django.core.exceptions.SuspiciousOperation` (``RequestDataTooBig``) is
1039 raised. The check is done when accessing ``request.body`` or ``request.POST``
1040 and is calculated against the total request size excluding any file upload
1041 data. You can set this to ``None`` to disable the check. Applications that are
1042 expected to receive unusually large form posts should tune this setting.
1043
1044 The amount of request data is correlated to the amount of memory needed to
1045 process the request and populate the GET and POST dictionaries. Large requests
1046 could be used as a denial-of-service attack vector if left unchecked. Since web
1047 servers don't typically perform deep request inspection, it's not possible to
1048 perform a similar check at that level.
1049
1050 See also :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`.
1051
1052 .. setting:: DATA_UPLOAD_MAX_NUMBER_FIELDS
1053
1054 ``DATA_UPLOAD_MAX_NUMBER_FIELDS``
1055 ---------------------------------
1056
1057 Default: ``1000``
1058
1059 The maximum number of parameters that may be received via GET or POST before a
1060 :exc:`~django.core.exceptions.SuspiciousOperation` (``TooManyFields``) is
1061 raised. You can set this to ``None`` to disable the check. Applications that
1062 are expected to receive an unusually large number of form fields should tune
1063 this setting.
1064
1065 The number of request parameters is correlated to the amount of time needed to
1066 process the request and populate the GET and POST dictionaries. Large requests
1067 could be used as a denial-of-service attack vector if left unchecked. Since web
1068 servers don't typically perform deep request inspection, it's not possible to
1069 perform a similar check at that level.
1070
1071 .. setting:: DATA_UPLOAD_MAX_NUMBER_FILES
1072
1073 ``DATA_UPLOAD_MAX_NUMBER_FILES``
1074 --------------------------------
1075
1076 Default: ``100``
1077
1078 The maximum number of files that may be received via POST in a
1079 ``multipart/form-data`` encoded request before a
1080 :exc:`~django.core.exceptions.SuspiciousOperation` (``TooManyFiles``) is
1081 raised. You can set this to ``None`` to disable the check. Applications that
1082 are expected to receive an unusually large number of file fields should tune
1083 this setting.
1084
1085 The number of accepted files is correlated to the amount of time and memory
1086 needed to process the request. Large requests could be used as a
1087 denial-of-service attack vector if left unchecked. Since web servers don't
1088 typically perform deep request inspection, it's not possible to perform a
1089 similar check at that level.
1090
1091 .. setting:: DATABASE_ROUTERS
1092
1093 ``DATABASE_ROUTERS``
1094 --------------------
1095
1096 Default: ``[]`` (Empty list)
1097
1098 The list of routers that will be used to determine which database
1099 to use when performing a database query.
1100
1101 See the documentation on :ref:`automatic database routing in multi
1102 database configurations <topics-db-multi-db-routing>`.
1103
1104 .. setting:: DATE_FORMAT
1105
1106 ``DATE_FORMAT``
1107 ---------------
1108
1109 Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``)
1110
1111 The default formatting to use for displaying date fields in any part of the
1112 system. Note that the locale-dictated format has higher precedence and will be
1113 applied instead. See :tfilter:`allowed date format strings <date>`.
1114
1115 See also :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT` and :setting:`SHORT_DATE_FORMAT`.
1116
1117 .. setting:: DATE_INPUT_FORMATS
1118
1119 ``DATE_INPUT_FORMATS``
1120 ----------------------
1121
1122 Default::
1123
1124 [
1125 "%Y-%m-%d", # '2006-10-25'
1126 "%m/%d/%Y", # '10/25/2006'
1127 "%m/%d/%y", # '10/25/06'
1128 "%b %d %Y", # 'Oct 25 2006'
1129 "%b %d, %Y", # 'Oct 25, 2006'
1130 "%d %b %Y", # '25 Oct 2006'
1131 "%d %b, %Y", # '25 Oct, 2006'
1132 "%B %d %Y", # 'October 25 2006'
1133 "%B %d, %Y", # 'October 25, 2006'
1134 "%d %B %Y", # '25 October 2006'
1135 "%d %B, %Y", # '25 October, 2006'
1136 ]
1137
1138 A list of formats that will be accepted when inputting data on a date field.
1139 Formats will be tried in order, using the first valid one. Note that these
1140 format strings use Python's :ref:`datetime module syntax
1141 <strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
1142 template filter.
1143
1144 The locale-dictated format has higher precedence and will be applied instead.
1145
1146 See also :setting:`DATETIME_INPUT_FORMATS` and :setting:`TIME_INPUT_FORMATS`.
1147
1148 .. setting:: DATETIME_FORMAT
1149
1150 ``DATETIME_FORMAT``
1151 -------------------
1152
1153 Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``)
1154
1155 The default formatting to use for displaying datetime fields in any part of the
1156 system. Note that the locale-dictated format has higher precedence and will be
1157 applied instead. See :tfilter:`allowed date format strings <date>`.
1158
1159 See also :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT` and :setting:`SHORT_DATETIME_FORMAT`.
1160
1161 .. setting:: DATETIME_INPUT_FORMATS
1162
1163 ``DATETIME_INPUT_FORMATS``
1164 --------------------------
1165
1166 Default::
1167
1168 [
1169 "%Y-%m-%d %H:%M:%S", # '2006-10-25 14:30:59'
1170 "%Y-%m-%d %H:%M:%S.%f", # '2006-10-25 14:30:59.000200'
1171 "%Y-%m-%d %H:%M", # '2006-10-25 14:30'
1172 "%m/%d/%Y %H:%M:%S", # '10/25/2006 14:30:59'
1173 "%m/%d/%Y %H:%M:%S.%f", # '10/25/2006 14:30:59.000200'
1174 "%m/%d/%Y %H:%M", # '10/25/2006 14:30'
1175 "%m/%d/%y %H:%M:%S", # '10/25/06 14:30:59'
1176 "%m/%d/%y %H:%M:%S.%f", # '10/25/06 14:30:59.000200'
1177 "%m/%d/%y %H:%M", # '10/25/06 14:30'
1178 ]
1179
1180 A list of formats that will be accepted when inputting data on a datetime
1181 field. Formats will be tried in order, using the first valid one. Note that
1182 these format strings use Python's :ref:`datetime module syntax
1183 <strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
1184 template filter. Date-only formats are not included as datetime fields will
1185 automatically try :setting:`DATE_INPUT_FORMATS` in last resort.
1186
1187 The locale-dictated format has higher precedence and will be applied instead.
1188
1189 See also :setting:`DATE_INPUT_FORMATS` and :setting:`TIME_INPUT_FORMATS`.
1190
1191 .. setting:: DEBUG
1192
1193 ``DEBUG``
1194 ---------
1195
1196 Default: ``False``
1197
1198 A boolean that turns on/off debug mode.
1199
1200 Never deploy a site into production with :setting:`DEBUG` turned on.
1201
1202 One of the main features of debug mode is the display of detailed error pages.
1203 If your app raises an exception when :setting:`DEBUG` is ``True``, Django will
1204 display a detailed traceback, including a lot of metadata about your
1205 environment, such as all the currently defined Django settings (from
1206 ``settings.py``).
1207
1208 As a security measure, Django will *not* include settings that might be
1209 sensitive, such as :setting:`SECRET_KEY`. Specifically, it will exclude any
1210 setting whose name includes any of the following:
1211
1212 * ``'API'``
1213 * ``'KEY'``
1214 * ``'PASS'``
1215 * ``'SECRET'``
1216 * ``'SIGNATURE'``
1217 * ``'TOKEN'``
1218
1219 Note that these are *partial* matches. ``'PASS'`` will also match PASSWORD,
1220 just as ``'TOKEN'`` will also match TOKENIZED and so on.
1221
1222 Still, note that there are always going to be sections of your debug output
1223 that are inappropriate for public consumption. File paths, configuration
1224 options and the like all give attackers extra information about your server.
1225
1226 It is also important to remember that when running with :setting:`DEBUG`
1227 turned on, Django will remember every SQL query it executes. This is useful
1228 when you're debugging, but it'll rapidly consume memory on a production server.
1229
1230 Finally, if :setting:`DEBUG` is ``False``, you also need to properly set
1231 the :setting:`ALLOWED_HOSTS` setting. Failing to do so will result in all
1232 requests being returned as "Bad Request (400)".
1233
1234 .. note::
1235
1236 The default :file:`settings.py` file created by :djadmin:`django-admin
1237 startproject <startproject>` sets ``DEBUG = True`` for convenience.
1238
1239 .. setting:: DEBUG_PROPAGATE_EXCEPTIONS
1240
1241 ``DEBUG_PROPAGATE_EXCEPTIONS``
1242 ------------------------------
1243
1244 Default: ``False``
1245
1246 If set to ``True``, Django's exception handling of view functions
1247 (:data:`~django.conf.urls.handler500`, or the debug view if :setting:`DEBUG`
1248 is ``True``) and logging of 500 responses (:ref:`django-request-logger`) is
1249 skipped and exceptions propagate upward.
1250
1251 This can be useful for some test setups. It shouldn't be used on a live site
1252 unless you want your web server (instead of Django) to generate "Internal
1253 Server Error" responses. In that case, make sure your server doesn't show the
1254 stack trace or other sensitive information in the response.
1255
1256 .. setting:: DECIMAL_SEPARATOR
1257
1258 ``DECIMAL_SEPARATOR``
1259 ---------------------
1260
1261 Default: ``'.'`` (Dot)
1262
1263 Default decimal separator used when formatting decimal numbers.
1264
1265 Note that the locale-dictated format has higher precedence and will be applied
1266 instead.
1267
1268 See also :setting:`NUMBER_GROUPING`, :setting:`THOUSAND_SEPARATOR` and
1269 :setting:`USE_THOUSAND_SEPARATOR`.
1270
1271 .. setting:: DEFAULT_AUTO_FIELD
1272
1273 ``DEFAULT_AUTO_FIELD``
1274 ----------------------
1275
1276 Default: ``'``:class:`django.db.models.AutoField`\ ``'``
1277
1278 Default primary key field type to use for models that don't have a field with
1279 :attr:`primary_key=True <django.db.models.Field.primary_key>`.
1280
1281 .. admonition:: Migrating auto-created through tables
1282
1283 The value of ``DEFAULT_AUTO_FIELD`` will be respected when creating new
1284 auto-created through tables for many-to-many relationships.
1285
1286 Unfortunately, the primary keys of existing auto-created through tables
1287 cannot currently be updated by the migrations framework.
1288
1289 This means that if you switch the value of ``DEFAULT_AUTO_FIELD`` and then
1290 generate migrations, the primary keys of the related models will be
1291 updated, as will the foreign keys from the through table, but the primary
1292 key of the auto-created through table will not be migrated.
1293
1294 In order to address this, you should add a
1295 :class:`~django.db.migrations.operations.RunSQL` operation to your
1296 migrations to perform the required ``ALTER TABLE`` step. You can check the
1297 existing table name through ``sqlmigrate``, ``dbshell``, or with the
1298 field’s ``remote_field.through._meta.db_table`` property.
1299
1300 Explicitly defined through models are already handled by the migrations
1301 system.
1302
1303 Allowing automatic migrations for the primary key of existing auto-created
1304 through tables :ticket:`may be implemented at a later date <32674>`.
1305
1306 .. setting:: DEFAULT_CHARSET
1307
1308 ``DEFAULT_CHARSET``
1309 -------------------
1310
1311 Default: ``'utf-8'``
1312
1313 Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't
1314 manually specified. Used when constructing the ``Content-Type`` header.
1315
1316 .. setting:: DEFAULT_EXCEPTION_REPORTER
1317
1318 ``DEFAULT_EXCEPTION_REPORTER``
1319 ------------------------------
1320
1321 Default: ``'``:class:`django.views.debug.ExceptionReporter`\ ``'``
1322
1323 Default exception reporter class to be used if none has been assigned to the
1324 :class:`~django.http.HttpRequest` instance yet. See
1325 :ref:`custom-error-reports`.
1326
1327 .. setting:: DEFAULT_EXCEPTION_REPORTER_FILTER
1328
1329 ``DEFAULT_EXCEPTION_REPORTER_FILTER``
1330 -------------------------------------
1331
1332 Default: ``'``:class:`django.views.debug.SafeExceptionReporterFilter`\ ``'``
1333
1334 Default exception reporter filter class to be used if none has been assigned to
1335 the :class:`~django.http.HttpRequest` instance yet.
1336 See :ref:`Filtering error reports<filtering-error-reports>`.
1337
1338 .. setting:: DEFAULT_FROM_EMAIL
1339
1340 ``DEFAULT_FROM_EMAIL``
1341 ----------------------
1342
1343 Default: ``'webmaster@localhost'``
1344
1345 Default email address for automated correspondence from the site manager(s).
1346 This address is used in the ``From:`` header of outgoing emails and can take
1347 any format valid in the chosen email sending protocol.
1348
1349 This doesn't affect error messages sent to :setting:`ADMINS` and
1350 :setting:`MANAGERS`. See :setting:`SERVER_EMAIL` for that.
1351
1352 .. setting:: DEFAULT_INDEX_TABLESPACE
1353
1354 ``DEFAULT_INDEX_TABLESPACE``
1355 ----------------------------
1356
1357 Default: ``''`` (Empty string)
1358
1359 Default tablespace to use for indexes on fields that don't specify
1360 one, if the backend supports it (see :doc:`/topics/db/tablespaces`).
1361
1362 .. setting:: DEFAULT_TABLESPACE
1363
1364 ``DEFAULT_TABLESPACE``
1365 ----------------------
1366
1367 Default: ``''`` (Empty string)
1368
1369 Default tablespace to use for models that don't specify one, if the
1370 backend supports it (see :doc:`/topics/db/tablespaces`).
1371
1372 .. setting:: DISALLOWED_USER_AGENTS
1373
1374 ``DISALLOWED_USER_AGENTS``
1375 --------------------------
1376
1377 Default: ``[]`` (Empty list)
1378
1379 List of compiled regular expression objects representing User-Agent strings
1380 that are not allowed to visit any page, systemwide. Use this for bots/crawlers.
1381 This is only used if ``CommonMiddleware`` is installed (see
1382 :doc:`/topics/http/middleware`).
1383
1384 .. setting:: EMAIL_BACKEND
1385
1386 ``EMAIL_BACKEND``
1387 -----------------
1388
1389 Default: ``'``:class:`django.core.mail.backends.smtp.EmailBackend`\ ``'``
1390
1391 The backend to use for sending emails. For the list of available backends see
1392 :ref:`topic-email-backends`.
1393
1394 .. setting:: EMAIL_FILE_PATH
1395
1396 ``EMAIL_FILE_PATH``
1397 -------------------
1398
1399 Default: Not defined
1400
1401 The directory used by the :ref:`file email backend <topic-email-file-backend>`
1402 to store output files.
1403
1404 .. setting:: EMAIL_HOST
1405
1406 ``EMAIL_HOST``
1407 --------------
1408
1409 Default: ``'localhost'``
1410
1411 The host to use for sending email.
1412
1413 See also :setting:`EMAIL_PORT`.
1414
1415 .. setting:: EMAIL_HOST_PASSWORD
1416
1417 ``EMAIL_HOST_PASSWORD``
1418 -----------------------
1419
1420 Default: ``''`` (Empty string)
1421
1422 Password to use for the SMTP server defined in :setting:`EMAIL_HOST`. This
1423 setting is used in conjunction with :setting:`EMAIL_HOST_USER` when
1424 authenticating to the SMTP server. If either of these settings is empty,
1425 Django won't attempt authentication.
1426
1427 See also :setting:`EMAIL_HOST_USER`.
1428
1429 .. setting:: EMAIL_HOST_USER
1430
1431 ``EMAIL_HOST_USER``
1432 -------------------
1433
1434 Default: ``''`` (Empty string)
1435
1436 Username to use for the SMTP server defined in :setting:`EMAIL_HOST`.
1437 If empty, Django won't attempt authentication.
1438
1439 See also :setting:`EMAIL_HOST_PASSWORD`.
1440
1441 .. setting:: EMAIL_PORT
1442
1443 ``EMAIL_PORT``
1444 --------------
1445
1446 Default: ``25``
1447
1448 Port to use for the SMTP server defined in :setting:`EMAIL_HOST`.
1449
1450 .. setting:: EMAIL_SUBJECT_PREFIX
1451
1452 ``EMAIL_SUBJECT_PREFIX``
1453 ------------------------
1454
1455 Default: ``'[Django] '``
1456
1457 Subject-line prefix for email messages sent with ``django.core.mail.mail_admins``
1458 or ``django.core.mail.mail_managers``. You'll probably want to include the
1459 trailing space.
1460
1461 .. setting:: EMAIL_USE_LOCALTIME
1462
1463 ``EMAIL_USE_LOCALTIME``
1464 -----------------------
1465
1466 Default: ``False``
1467
1468 Whether to send the SMTP ``Date`` header of email messages in the local time
1469 zone (``True``) or in UTC (``False``).
1470
1471 .. setting:: EMAIL_USE_TLS
1472
1473 ``EMAIL_USE_TLS``
1474 -----------------
1475
1476 Default: ``False``
1477
1478 Whether to use a TLS (secure) connection when talking to the SMTP server.
1479 This is used for explicit TLS connections, generally on port 587. If you are
1480 experiencing hanging connections, see the implicit TLS setting
1481 :setting:`EMAIL_USE_SSL`.
1482
1483 .. setting:: EMAIL_USE_SSL
1484
1485 ``EMAIL_USE_SSL``
1486 -----------------
1487
1488 Default: ``False``
1489
1490 Whether to use an implicit TLS (secure) connection when talking to the SMTP
1491 server. In most email documentation this type of TLS connection is referred
1492 to as SSL. It is generally used on port 465. If you are experiencing problems,
1493 see the explicit TLS setting :setting:`EMAIL_USE_TLS`.
1494
1495 Note that :setting:`EMAIL_USE_TLS`/:setting:`EMAIL_USE_SSL` are mutually
1496 exclusive, so only set one of those settings to ``True``.
1497
1498 .. setting:: EMAIL_SSL_CERTFILE
1499
1500 ``EMAIL_SSL_CERTFILE``
1501 ----------------------
1502
1503 Default: ``None``
1504
1505 If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True`` and the
1506 secure connection to the SMTP server requires client authentication, use this
1507 setting to specify the path to a PEM-formatted certificate chain file, which
1508 must be used in conjunction with :setting:`EMAIL_SSL_KEYFILE`.
1509
1510 ``EMAIL_SSL_CERTFILE`` should not be used with a self-signed server certificate
1511 or a certificate from a private certificate authority (CA). In such cases, the
1512 server's certificate (or the root certificate of the private CA) should be
1513 installed into the system's CA bundle. This can be done by following
1514 platform-specific instructions for installing a root CA certificate,
1515 or by using OpenSSL's ``SSL_CERT_FILE`` or ``SSL_CERT_DIR`` environment
1516 variables to specify a custom certificate bundle (if modifying the system
1517 bundle is not possible or desired).
1518
1519 For more complex scenarios, the SMTP
1520 :class:`~django.core.mail.backends.smtp.EmailBackend` can be subclassed to add
1521 root certificates to its ``ssl_context`` using
1522 :meth:`python:ssl.SSLContext.load_verify_locations`.
1523
1524 .. setting:: EMAIL_SSL_KEYFILE
1525
1526 ``EMAIL_SSL_KEYFILE``
1527 ---------------------
1528
1529 Default: ``None``
1530
1531 If :setting:`EMAIL_USE_SSL` or :setting:`EMAIL_USE_TLS` is ``True``, you can
1532 optionally specify the path to a PEM-formatted private key file for client
1533 authentication of the SSL connection along with :setting:`EMAIL_SSL_CERTFILE`.
1534
1535 Note that setting :setting:`EMAIL_SSL_CERTFILE` and :setting:`EMAIL_SSL_KEYFILE`
1536 doesn't result in any certificate checking. They're passed to the underlying SSL
1537 connection. Please refer to the documentation of Python's
1538 :meth:`python:ssl.SSLContext.wrap_socket` function for details on how the
1539 certificate chain file and private key file are handled.
1540
1541 .. setting:: EMAIL_TIMEOUT
1542
1543 ``EMAIL_TIMEOUT``
1544 -----------------
1545
1546 Default: ``None``
1547
1548 Specifies a timeout in seconds for blocking operations like the connection
1549 attempt.
1550
1551 .. setting:: FILE_UPLOAD_HANDLERS
1552
1553 ``FILE_UPLOAD_HANDLERS``
1554 ------------------------
1555
1556 Default::
1557
1558 [
1559 "django.core.files.uploadhandler.MemoryFileUploadHandler",
1560 "django.core.files.uploadhandler.TemporaryFileUploadHandler",
1561 ]
1562
1563 A list of handlers to use for uploading. Changing this setting allows complete
1564 customization -- even replacement -- of Django's upload process.
1565
1566 See :doc:`/topics/files` for details.
1567
1568 .. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE
1569
1570 ``FILE_UPLOAD_MAX_MEMORY_SIZE``
1571 -------------------------------
1572
1573 Default: ``2621440`` (i.e. 2.5 MB).
1574
1575 The maximum size (in bytes) that an upload will be before it gets streamed to
1576 the file system. See :doc:`/topics/files` for details.
1577
1578 See also :setting:`DATA_UPLOAD_MAX_MEMORY_SIZE`.
1579
1580 .. setting:: FILE_UPLOAD_DIRECTORY_PERMISSIONS
1581
1582 ``FILE_UPLOAD_DIRECTORY_PERMISSIONS``
1583 -------------------------------------
1584
1585 Default: ``None``
1586
1587 The numeric mode to apply to directories created in the process of uploading
1588 files.
1589
1590 This setting also determines the default permissions for collected static
1591 directories when using the :djadmin:`collectstatic` management command. See
1592 :djadmin:`collectstatic` for details on overriding it.
1593
1594 This value mirrors the functionality and caveats of the
1595 :setting:`FILE_UPLOAD_PERMISSIONS` setting.
1596
1597 .. setting:: FILE_UPLOAD_PERMISSIONS
1598
1599 ``FILE_UPLOAD_PERMISSIONS``
1600 ---------------------------
1601
1602 Default: ``0o644``
1603
1604 The numeric mode (i.e. ``0o644``) to set newly uploaded files to. For
1605 more information about what these modes mean, see the documentation for
1606 :func:`os.chmod`.
1607
1608 If ``None``, you'll get operating-system dependent behavior. On most platforms,
1609 temporary files will have a mode of ``0o600``, and files saved from memory will
1610 be saved using the system's standard umask.
1611
1612 For security reasons, these permissions aren't applied to the temporary files
1613 that are stored in :setting:`FILE_UPLOAD_TEMP_DIR`.
1614
1615 This setting also determines the default permissions for collected static files
1616 when using the :djadmin:`collectstatic` management command. See
1617 :djadmin:`collectstatic` for details on overriding it.
1618
1619 .. warning::
1620
1621 **Always prefix the mode with** ``0o`` **.**
1622
1623 If you're not familiar with file modes, please note that the ``0o`` prefix
1624 is very important: it indicates an octal number, which is the way that
1625 modes must be specified. If you try to use ``644``, you'll get totally
1626 incorrect behavior.
1627
1628 .. setting:: FILE_UPLOAD_TEMP_DIR
1629
1630 ``FILE_UPLOAD_TEMP_DIR``
1631 ------------------------
1632
1633 Default: ``None``
1634
1635 The directory to store data to (typically files larger than
1636 :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`) temporarily while uploading files.
1637 If ``None``, Django will use the standard temporary directory for the operating
1638 system. For example, this will default to ``/tmp`` on \*nix-style operating
1639 systems.
1640
1641 See :doc:`/topics/files` for details.
1642
1643 .. setting:: FIRST_DAY_OF_WEEK
1644
1645 ``FIRST_DAY_OF_WEEK``
1646 ---------------------
1647
1648 Default: ``0`` (Sunday)
1649
1650 A number representing the first day of the week. This is especially useful
1651 when displaying a calendar. This value is only used when not using
1652 format internationalization, or when a format cannot be found for the
1653 current locale.
1654
1655 The value must be an integer from 0 to 6, where 0 means Sunday, 1 means
1656 Monday and so on.
1657
1658 .. setting:: FIXTURE_DIRS
1659
1660 ``FIXTURE_DIRS``
1661 ----------------
1662
1663 Default: ``[]`` (Empty list)
1664
1665 List of directories searched for :ref:`fixture <fixtures-explanation>` files,
1666 in addition to the ``fixtures`` directory of each application, in search order.
1667
1668 Note that these paths should use Unix-style forward slashes, even on Windows.
1669
1670 See :ref:`initial-data-via-fixtures` and :ref:`topics-testing-fixtures`.
1671
1672 .. setting:: FORCE_SCRIPT_NAME
1673
1674 ``FORCE_SCRIPT_NAME``
1675 ---------------------
1676
1677 Default: ``None``
1678
1679 If not ``None``, this will be used as the value of the ``SCRIPT_NAME``
1680 environment variable in any HTTP request. This setting can be used to override
1681 the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version
1682 of the preferred value or not supplied at all. It is also used by
1683 :func:`django.setup()` to set the URL resolver script prefix outside of the
1684 request/response cycle (e.g. in management commands and standalone scripts) to
1685 generate correct URLs when ``FORCE_SCRIPT_NAME`` is provided.
1686
1687 .. setting:: FORM_RENDERER
1688
1689 ``FORM_RENDERER``
1690 -----------------
1691
1692 Default: ``'``:class:`django.forms.renderers.DjangoTemplates`\ ``'``
1693
1694 The class that renders forms and form widgets. It must implement
1695 :ref:`the low-level render API <low-level-widget-render-api>`. Included form
1696 renderers are:
1697
1698 * ``'``:class:`django.forms.renderers.DjangoTemplates`\ ``'``
1699 * ``'``:class:`django.forms.renderers.Jinja2`\ ``'``
1700 * ``'``:class:`django.forms.renderers.TemplatesSetting`\ ``'``
1701
1702 .. setting:: FORMS_URLFIELD_ASSUME_HTTPS
1703
1704 ``FORMS_URLFIELD_ASSUME_HTTPS``
1705 -------------------------------
1706
1707 .. deprecated:: 5.0
1708
1709 Default: ``False``
1710
1711 Set this transitional setting to ``True`` to opt into using ``"https"`` as the
1712 new default value of :attr:`URLField.assume_scheme
1713 <django.forms.URLField.assume_scheme>` during the Django 5.x release cycle.
1714
1715 .. setting:: FORMAT_MODULE_PATH
1716
1717 ``FORMAT_MODULE_PATH``
1718 ----------------------
1719
1720 Default: ``None``
1721
1722 A full Python path to a Python package that contains custom format definitions
1723 for project locales. If not ``None``, Django will check for a ``formats.py``
1724 file, under the directory named as the current locale, and will use the
1725 formats defined in this file.
1726
1727 The name of the directory containing the format definitions is expected to be
1728 named using :term:`locale name` notation, for example ``de``, ``pt_BR``,
1729 ``en_US``, etc.
1730
1731 For example, if :setting:`FORMAT_MODULE_PATH` is set to ``mysite.formats``,
1732 and current language is ``en`` (English), Django will expect a directory tree
1733 like:
1734
1735 .. code-block:: text
1736
1737 mysite/
1738 formats/
1739 __init__.py
1740 en/
1741 __init__.py
1742 formats.py
1743
1744 You can also set this setting to a list of Python paths, for example::
1745
1746 FORMAT_MODULE_PATH = [
1747 "mysite.formats",
1748 "some_app.formats",
1749 ]
1750
1751 When Django searches for a certain format, it will go through all given Python
1752 paths until it finds a module that actually defines the given format. This
1753 means that formats defined in packages farther up in the list will take
1754 precedence over the same formats in packages farther down.
1755
1756 Available formats are:
1757
1758 * :setting:`DATE_FORMAT`
1759 * :setting:`DATE_INPUT_FORMATS`
1760 * :setting:`DATETIME_FORMAT`,
1761 * :setting:`DATETIME_INPUT_FORMATS`
1762 * :setting:`DECIMAL_SEPARATOR`
1763 * :setting:`FIRST_DAY_OF_WEEK`
1764 * :setting:`MONTH_DAY_FORMAT`
1765 * :setting:`NUMBER_GROUPING`
1766 * :setting:`SHORT_DATE_FORMAT`
1767 * :setting:`SHORT_DATETIME_FORMAT`
1768 * :setting:`THOUSAND_SEPARATOR`
1769 * :setting:`TIME_FORMAT`
1770 * :setting:`TIME_INPUT_FORMATS`
1771 * :setting:`YEAR_MONTH_FORMAT`
1772
1773 .. setting:: IGNORABLE_404_URLS
1774
1775 ``IGNORABLE_404_URLS``
1776 ----------------------
1777
1778 Default: ``[]`` (Empty list)
1779
1780 List of compiled regular expression objects describing URLs that should be
1781 ignored when reporting HTTP 404 errors via email (see
1782 :doc:`/howto/error-reporting`). Regular expressions are matched against
1783 :meth:`request's full paths <django.http.HttpRequest.get_full_path>` (including
1784 query string, if any). Use this if your site does not provide a commonly
1785 requested file such as ``favicon.ico`` or ``robots.txt``.
1786
1787 This is only used if
1788 :class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled (see
1789 :doc:`/topics/http/middleware`).
1790
1791 .. setting:: INSTALLED_APPS
1792
1793 ``INSTALLED_APPS``
1794 ------------------
1795
1796 Default: ``[]`` (Empty list)
1797
1798 A list of strings designating all applications that are enabled in this
1799 Django installation. Each string should be a dotted Python path to:
1800
1801 * an application configuration class (preferred), or
1802 * a package containing an application.
1803
1804 :doc:`Learn more about application configurations </ref/applications>`.
1805
1806 .. admonition:: Use the application registry for introspection
1807
1808 Your code should never access :setting:`INSTALLED_APPS` directly. Use
1809 :attr:`django.apps.apps` instead.
1810
1811 .. admonition:: Application names and labels must be unique in
1812 :setting:`INSTALLED_APPS`
1813
1814 Application :attr:`names <django.apps.AppConfig.name>` — the dotted Python
1815 path to the application package — must be unique. There is no way to
1816 include the same application twice, short of duplicating its code under
1817 another name.
1818
1819 Application :attr:`labels <django.apps.AppConfig.label>` — by default the
1820 final part of the name — must be unique too. For example, you can't
1821 include both ``django.contrib.auth`` and ``myproject.auth``. However, you
1822 can relabel an application with a custom configuration that defines a
1823 different :attr:`~django.apps.AppConfig.label`.
1824
1825 These rules apply regardless of whether :setting:`INSTALLED_APPS`
1826 references application configuration classes or application packages.
1827
1828 When several applications provide different versions of the same resource
1829 (template, static file, management command, translation), the application
1830 listed first in :setting:`INSTALLED_APPS` has precedence.
1831
1832 .. setting:: INTERNAL_IPS
1833
1834 ``INTERNAL_IPS``
1835 ----------------
1836
1837 Default: ``[]`` (Empty list)
1838
1839 A list of IP addresses, as strings, that:
1840
1841 * Allow the :func:`~django.template.context_processors.debug` context processor
1842 to add some variables to the template context.
1843 * Can use the :ref:`admindocs bookmarklets <admindocs-bookmarklets>` even if
1844 not logged in as a staff user.
1845 * Are marked as "internal" (as opposed to "EXTERNAL") in
1846 :class:`~django.utils.log.AdminEmailHandler` emails.
1847
1848 .. setting:: LANGUAGE_CODE
1849
1850 ``LANGUAGE_CODE``
1851 -----------------
1852
1853 Default: ``'en-us'``
1854
1855 A string representing the language code for this installation. This should be in
1856 standard :term:`language ID format <language code>`. For example, U.S. English
1857 is ``"en-us"``. See also the `list of language identifiers`_ and
1858 :doc:`/topics/i18n/index`.
1859
1860 It serves three purposes:
1861
1862 * If the locale middleware isn't in use, it decides which translation is served
1863 to all users.
1864 * If the locale middleware is active, it provides a fallback language in case the
1865 user's preferred language can't be determined or is not supported by the
1866 website. It also provides the fallback translation when a translation for a
1867 given literal doesn't exist for the user's preferred language.
1868 * If localization is explicitly disabled via the :tfilter:`unlocalize` filter
1869 or the :ttag:`{% localize off %}<localize>` tag, it provides fallback
1870 localization formats which will be applied instead. See
1871 :ref:`controlling localization in templates <topic-l10n-templates>` for
1872 details.
1873
1874 See :ref:`how-django-discovers-language-preference` for more details.
1875
1876 .. _list of language identifiers: http://www.i18nguy.com/unicode/language-identifiers.html
1877
1878 .. setting:: LANGUAGE_COOKIE_AGE
1879
1880 ``LANGUAGE_COOKIE_AGE``
1881 -----------------------
1882
1883 Default: ``None`` (expires at browser close)
1884
1885 The age of the language cookie, in seconds.
1886
1887 .. setting:: LANGUAGE_COOKIE_DOMAIN
1888
1889 ``LANGUAGE_COOKIE_DOMAIN``
1890 --------------------------
1891
1892 Default: ``None``
1893
1894 The domain to use for the language cookie. Set this to a string such as
1895 ``"example.com"`` for cross-domain cookies, or use ``None`` for a standard
1896 domain cookie.
1897
1898 Be cautious when updating this setting on a production site. If you update
1899 this setting to enable cross-domain cookies on a site that previously used
1900 standard domain cookies, existing user cookies that have the old domain
1901 will not be updated. This will result in site users being unable to switch
1902 the language as long as these cookies persist. The only safe and reliable
1903 option to perform the switch is to change the language cookie name
1904 permanently (via the :setting:`LANGUAGE_COOKIE_NAME` setting) and to add
1905 a middleware that copies the value from the old cookie to a new one and then
1906 deletes the old one.
1907
1908 .. setting:: LANGUAGE_COOKIE_HTTPONLY
1909
1910 ``LANGUAGE_COOKIE_HTTPONLY``
1911 ----------------------------
1912
1913 Default: ``False``
1914
1915 Whether to use ``HttpOnly`` flag on the language cookie. If this is set to
1916 ``True``, client-side JavaScript will not be able to access the language
1917 cookie.
1918
1919 See :setting:`SESSION_COOKIE_HTTPONLY` for details on ``HttpOnly``.
1920
1921 .. setting:: LANGUAGE_COOKIE_NAME
1922
1923 ``LANGUAGE_COOKIE_NAME``
1924 ------------------------
1925
1926 Default: ``'django_language'``
1927
1928 The name of the cookie to use for the language cookie. This can be whatever
1929 you want (as long as it's different from the other cookie names in your
1930 application). See :doc:`/topics/i18n/index`.
1931
1932 .. setting:: LANGUAGE_COOKIE_PATH
1933
1934 ``LANGUAGE_COOKIE_PATH``
1935 ------------------------
1936
1937 Default: ``'/'``
1938
1939 The path set on the language cookie. This should either match the URL path of your
1940 Django installation or be a parent of that path.
1941
1942 This is useful if you have multiple Django instances running under the same
1943 hostname. They can use different cookie paths and each instance will only see
1944 its own language cookie.
1945
1946 Be cautious when updating this setting on a production site. If you update this
1947 setting to use a deeper path than it previously used, existing user cookies that
1948 have the old path will not be updated. This will result in site users being
1949 unable to switch the language as long as these cookies persist. The only safe
1950 and reliable option to perform the switch is to change the language cookie name
1951 permanently (via the :setting:`LANGUAGE_COOKIE_NAME` setting), and to add
1952 a middleware that copies the value from the old cookie to a new one and then
1953 deletes the one.
1954
1955 .. setting:: LANGUAGE_COOKIE_SAMESITE
1956
1957 ``LANGUAGE_COOKIE_SAMESITE``
1958 ----------------------------
1959
1960 Default: ``None``
1961
1962 The value of the `SameSite`_ flag on the language cookie. This flag prevents the
1963 cookie from being sent in cross-site requests.
1964
1965 See :setting:`SESSION_COOKIE_SAMESITE` for details about ``SameSite``.
1966
1967 .. setting:: LANGUAGE_COOKIE_SECURE
1968
1969 ``LANGUAGE_COOKIE_SECURE``
1970 --------------------------
1971
1972 Default: ``False``
1973
1974 Whether to use a secure cookie for the language cookie. If this is set to
1975 ``True``, the cookie will be marked as "secure", which means browsers may
1976 ensure that the cookie is only sent under an HTTPS connection.
1977
1978 .. setting:: LANGUAGES
1979
1980 ``LANGUAGES``
1981 -------------
1982
1983 Default: A list of all available languages. This list is continually growing
1984 and including a copy here would inevitably become rapidly out of date. You can
1985 see the current list of translated languages by looking in
1986 :source:`django/conf/global_settings.py`.
1987
1988 The list is a list of 2-tuples in the format
1989 (:term:`language code<language code>`, ``language name``) -- for example,
1990 ``('ja', 'Japanese')``.
1991 This specifies which languages are available for language selection. See
1992 :doc:`/topics/i18n/index`.
1993
1994 Generally, the default value should suffice. Only set this setting if you want
1995 to restrict language selection to a subset of the Django-provided languages.
1996
1997 If you define a custom :setting:`LANGUAGES` setting, you can mark the
1998 language names as translation strings using the
1999 :func:`~django.utils.translation.gettext_lazy` function.
2000
2001 Here's a sample settings file::
2002
2003 from django.utils.translation import gettext_lazy as _
2004
2005 LANGUAGES = [
2006 ("de", _("German")),
2007 ("en", _("English")),
2008 ]
2009
2010 .. setting:: LANGUAGES_BIDI
2011
2012 ``LANGUAGES_BIDI``
2013 ------------------
2014
2015 Default: A list of all language codes that are written right-to-left. You can
2016 see the current list of these languages by looking in
2017 :source:`django/conf/global_settings.py`.
2018
2019 The list contains :term:`language codes<language code>` for languages that are
2020 written right-to-left.
2021
2022 Generally, the default value should suffice. Only set this setting if you want
2023 to restrict language selection to a subset of the Django-provided languages.
2024 If you define a custom :setting:`LANGUAGES` setting, the list of bidirectional
2025 languages may contain language codes which are not enabled on a given site.
2026
2027 .. setting:: LOCALE_PATHS
2028
2029 ``LOCALE_PATHS``
2030 ----------------
2031
2032 Default: ``[]`` (Empty list)
2033
2034 A list of directories where Django looks for translation files.
2035 See :ref:`how-django-discovers-translations`.
2036
2037 Example::
2038
2039 LOCALE_PATHS = [
2040 "/home/www/project/common_files/locale",
2041 "/var/local/translations/locale",
2042 ]
2043
2044 Django will look within each of these paths for the ``<locale_code>/LC_MESSAGES``
2045 directories containing the actual translation files.
2046
2047 .. setting:: LOGGING
2048
2049 ``LOGGING``
2050 -----------
2051
2052 Default: A logging configuration dictionary.
2053
2054 A data structure containing configuration information. When not-empty, the
2055 contents of this data structure will be passed as the argument to the
2056 configuration method described in :setting:`LOGGING_CONFIG`.
2057
2058 Among other things, the default logging configuration passes HTTP 500 server
2059 errors to an email log handler when :setting:`DEBUG` is ``False``. See also
2060 :ref:`configuring-logging`.
2061
2062 You can see the default logging configuration by looking in
2063 :source:`django/utils/log.py`.
2064
2065 .. setting:: LOGGING_CONFIG
2066
2067 ``LOGGING_CONFIG``
2068 ------------------
2069
2070 Default: ``'logging.config.dictConfig'``
2071
2072 A path to a callable that will be used to configure logging in the
2073 Django project. Points at an instance of Python's :ref:`dictConfig
2074 <logging-config-dictschema>` configuration method by default.
2075
2076 If you set :setting:`LOGGING_CONFIG` to ``None``, the logging
2077 configuration process will be skipped.
2078
2079 .. setting:: MANAGERS
2080
2081 ``MANAGERS``
2082 ------------
2083
2084 Default: ``[]`` (Empty list)
2085
2086 A list in the same format as :setting:`ADMINS` that specifies who should get
2087 broken link notifications when
2088 :class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled.
2089
2090 .. setting:: MEDIA_ROOT
2091
2092 ``MEDIA_ROOT``
2093 --------------
2094
2095 Default: ``''`` (Empty string)
2096
2097 Absolute filesystem path to the directory that will hold :doc:`user-uploaded
2098 files </topics/files>`.
2099
2100 Example: ``"/var/www/example.com/media/"``
2101
2102 See also :setting:`MEDIA_URL`.
2103
2104 .. warning::
2105
2106 :setting:`MEDIA_ROOT` and :setting:`STATIC_ROOT` must have different
2107 values. Before :setting:`STATIC_ROOT` was introduced, it was common to
2108 rely or fallback on :setting:`MEDIA_ROOT` to also serve static files;
2109 however, since this can have serious security implications, there is a
2110 validation check to prevent it.
2111
2112 .. setting:: MEDIA_URL
2113
2114 ``MEDIA_URL``
2115 -------------
2116
2117 Default: ``''`` (Empty string)
2118
2119 URL that handles the media served from :setting:`MEDIA_ROOT`, used
2120 for :doc:`managing stored files </topics/files>`. It must end in a slash if set
2121 to a non-empty value. You will need to :ref:`configure these files to be served
2122 <serving-uploaded-files-in-development>` in both development and production
2123 environments.
2124
2125 If you want to use ``{{ MEDIA_URL }}`` in your templates, add
2126 ``'django.template.context_processors.media'`` in the ``'context_processors'``
2127 option of :setting:`TEMPLATES`.
2128
2129 Example: ``"https://media.example.com/"``
2130
2131 .. warning::
2132
2133 There are security risks if you are accepting uploaded content from
2134 untrusted users! See the security guide's topic on
2135 :ref:`user-uploaded-content-security` for mitigation details.
2136
2137 .. warning::
2138
2139 :setting:`MEDIA_URL` and :setting:`STATIC_URL` must have different
2140 values. See :setting:`MEDIA_ROOT` for more details.
2141
2142 .. note::
2143
2144 If :setting:`MEDIA_URL` is a relative path, then it will be prefixed by the
2145 server-provided value of ``SCRIPT_NAME`` (or ``/`` if not set). This makes
2146 it easier to serve a Django application in a subpath without adding an
2147 extra configuration to the settings.
2148
2149 .. setting:: MIDDLEWARE
2150
2151 ``MIDDLEWARE``
2152 --------------
2153
2154 Default: ``None``
2155
2156 A list of middleware to use. See :doc:`/topics/http/middleware`.
2157
2158 .. setting:: MIGRATION_MODULES
2159
2160 ``MIGRATION_MODULES``
2161 ---------------------
2162
2163 Default: ``{}`` (Empty dictionary)
2164
2165 A dictionary specifying the package where migration modules can be found on a
2166 per-app basis. The default value of this setting is an empty dictionary, but
2167 the default package name for migration modules is ``migrations``.
2168
2169 Example::
2170
2171 {"blog": "blog.db_migrations"}
2172
2173 In this case, migrations pertaining to the ``blog`` app will be contained in
2174 the ``blog.db_migrations`` package.
2175
2176 If you provide the ``app_label`` argument, :djadmin:`makemigrations` will
2177 automatically create the package if it doesn't already exist.
2178
2179 When you supply ``None`` as a value for an app, Django will consider the app as
2180 an app without migrations regardless of an existing ``migrations`` submodule.
2181 This can be used, for example, in a test settings file to skip migrations while
2182 testing (tables will still be created for the apps' models). To disable
2183 migrations for all apps during tests, you can set the
2184 :setting:`MIGRATE <TEST_MIGRATE>` to ``False`` instead. If
2185 ``MIGRATION_MODULES`` is used in your general project settings, remember to use
2186 the :option:`migrate --run-syncdb` option if you want to create tables for the
2187 app.
2188
2189 .. setting:: MONTH_DAY_FORMAT
2190
2191 ``MONTH_DAY_FORMAT``
2192 --------------------
2193
2194 Default: ``'F j'``
2195
2196 The default formatting to use for date fields on Django admin change-list
2197 pages -- and, possibly, by other parts of the system -- in cases when only the
2198 month and day are displayed.
2199
2200 For example, when a Django admin change-list page is being filtered by a date
2201 drilldown, the header for a given day displays the day and month. Different
2202 locales have different formats. For example, U.S. English would say
2203 "January 1," whereas Spanish might say "1 Enero."
2204
2205 Note that the corresponding locale-dictated format has higher precedence and
2206 will be applied instead.
2207
2208 See :tfilter:`allowed date format strings <date>`. See also
2209 :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`,
2210 :setting:`TIME_FORMAT` and :setting:`YEAR_MONTH_FORMAT`.
2211
2212 .. setting:: NUMBER_GROUPING
2213
2214 ``NUMBER_GROUPING``
2215 -------------------
2216
2217 Default: ``0``
2218
2219 Number of digits grouped together on the integer part of a number.
2220
2221 Common use is to display a thousand separator. If this setting is ``0``, then
2222 no grouping will be applied to the number. If this setting is greater than
2223 ``0``, then :setting:`THOUSAND_SEPARATOR` will be used as the separator between
2224 those groups.
2225
2226 Some locales use non-uniform digit grouping, e.g. ``10,00,00,000`` in
2227 ``en_IN``. For this case, you can provide a sequence with the number of digit
2228 group sizes to be applied. The first number defines the size of the group
2229 preceding the decimal delimiter, and each number that follows defines the size
2230 of preceding groups. If the sequence is terminated with ``-1``, no further
2231 grouping is performed. If the sequence terminates with a ``0``, the last group
2232 size is used for the remainder of the number.
2233
2234 Example tuple for ``en_IN``::
2235
2236 NUMBER_GROUPING = (3, 2, 0)
2237
2238 Note that the locale-dictated format has higher precedence and will be applied
2239 instead.
2240
2241 See also :setting:`DECIMAL_SEPARATOR`, :setting:`THOUSAND_SEPARATOR` and
2242 :setting:`USE_THOUSAND_SEPARATOR`.
2243
2244 .. setting:: PREPEND_WWW
2245
2246 ``PREPEND_WWW``
2247 ---------------
2248
2249 Default: ``False``
2250
2251 Whether to prepend the "www." subdomain to URLs that don't have it. This is only
2252 used if :class:`~django.middleware.common.CommonMiddleware` is installed
2253 (see :doc:`/topics/http/middleware`). See also :setting:`APPEND_SLASH`.
2254
2255 .. setting:: ROOT_URLCONF
2256
2257 ``ROOT_URLCONF``
2258 ----------------
2259
2260 Default: Not defined
2261
2262 A string representing the full Python import path to your root URLconf, for
2263 example ``"mydjangoapps.urls"``. Can be overridden on a per-request basis by
2264 setting the attribute ``urlconf`` on the incoming ``HttpRequest``
2265 object. See :ref:`how-django-processes-a-request` for details.
2266
2267 .. setting:: SECRET_KEY
2268
2269 ``SECRET_KEY``
2270 --------------
2271
2272 Default: ``''`` (Empty string)
2273
2274 A secret key for a particular Django installation. This is used to provide
2275 :doc:`cryptographic signing </topics/signing>`, and should be set to a unique,
2276 unpredictable value.
2277
2278 :djadmin:`django-admin startproject <startproject>` automatically adds a
2279 randomly-generated ``SECRET_KEY`` to each new project.
2280
2281 Uses of the key shouldn't assume that it's text or bytes. Every use should go
2282 through :func:`~django.utils.encoding.force_str` or
2283 :func:`~django.utils.encoding.force_bytes` to convert it to the desired type.
2284
2285 Django will refuse to start if :setting:`SECRET_KEY` is not set.
2286
2287 .. warning::
2288
2289 **Keep this value secret.**
2290
2291 Running Django with a known :setting:`SECRET_KEY` defeats many of Django's
2292 security protections, and can lead to privilege escalation and remote code
2293 execution vulnerabilities.
2294
2295 The secret key is used for:
2296
2297 * All :doc:`sessions </topics/http/sessions>` if you are using
2298 any other session backend than ``django.contrib.sessions.backends.cache``,
2299 or are using the default
2300 :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()`.
2301 * All :doc:`messages </ref/contrib/messages>` if you are using
2302 :class:`~django.contrib.messages.storage.cookie.CookieStorage` or
2303 :class:`~django.contrib.messages.storage.fallback.FallbackStorage`.
2304 * All :class:`~django.contrib.auth.views.PasswordResetView` tokens.
2305 * Any usage of :doc:`cryptographic signing </topics/signing>`, unless a
2306 different key is provided.
2307
2308 When a secret key is no longer set as :setting:`SECRET_KEY` or contained within
2309 :setting:`SECRET_KEY_FALLBACKS` all of the above will be invalidated. When
2310 rotating your secret key, you should move the old key to
2311 :setting:`SECRET_KEY_FALLBACKS` temporarily. Secret keys are not used for
2312 passwords of users and key rotation will not affect them.
2313
2314 .. note::
2315
2316 The default :file:`settings.py` file created by :djadmin:`django-admin
2317 startproject <startproject>` creates a unique ``SECRET_KEY`` for
2318 convenience.
2319
2320 .. setting:: SECRET_KEY_FALLBACKS
2321
2322 ``SECRET_KEY_FALLBACKS``
2323 ------------------------
2324
2325 Default: ``[]``
2326
2327 A list of fallback secret keys for a particular Django installation. These are
2328 used to allow rotation of the ``SECRET_KEY``.
2329
2330 In order to rotate your secret keys, set a new ``SECRET_KEY`` and move the
2331 previous value to the beginning of ``SECRET_KEY_FALLBACKS``. Then remove the
2332 old values from the end of the ``SECRET_KEY_FALLBACKS`` when you are ready to
2333 expire the sessions, password reset tokens, and so on, that make use of them.
2334
2335 .. note::
2336
2337 Signing operations are computationally expensive. Having multiple old key
2338 values in ``SECRET_KEY_FALLBACKS`` adds additional overhead to all checks
2339 that don't match an earlier key.
2340
2341 As such, fallback values should be removed after an appropriate period,
2342 allowing for key rotation.
2343
2344 Uses of the secret key values shouldn't assume that they are text or bytes.
2345 Every use should go through :func:`~django.utils.encoding.force_str` or
2346 :func:`~django.utils.encoding.force_bytes` to convert it to the desired type.
2347
2348 .. setting:: SECURE_CONTENT_TYPE_NOSNIFF
2349
2350 ``SECURE_CONTENT_TYPE_NOSNIFF``
2351 -------------------------------
2352
2353 Default: ``True``
2354
2355 If ``True``, the :class:`~django.middleware.security.SecurityMiddleware`
2356 sets the :ref:`x-content-type-options` header on all responses that do not
2357 already have it.
2358
2359 .. setting:: SECURE_CROSS_ORIGIN_OPENER_POLICY
2360
2361 ``SECURE_CROSS_ORIGIN_OPENER_POLICY``
2362 -------------------------------------
2363
2364 Default: ``'same-origin'``
2365
2366 Unless set to ``None``, the
2367 :class:`~django.middleware.security.SecurityMiddleware` sets the
2368 :ref:`cross-origin-opener-policy` header on all responses that do not already
2369 have it to the value provided.
2370
2371 .. setting:: SECURE_HSTS_INCLUDE_SUBDOMAINS
2372
2373 ``SECURE_HSTS_INCLUDE_SUBDOMAINS``
2374 ----------------------------------
2375
2376 Default: ``False``
2377
2378 If ``True``, the :class:`~django.middleware.security.SecurityMiddleware` adds
2379 the ``includeSubDomains`` directive to the :ref:`http-strict-transport-security`
2380 header. It has no effect unless :setting:`SECURE_HSTS_SECONDS` is set to a
2381 non-zero value.
2382
2383 .. warning::
2384 Setting this incorrectly can irreversibly (for the value of
2385 :setting:`SECURE_HSTS_SECONDS`) break your site. Read the
2386 :ref:`http-strict-transport-security` documentation first.
2387
2388 .. setting:: SECURE_HSTS_PRELOAD
2389
2390 ``SECURE_HSTS_PRELOAD``
2391 -----------------------
2392
2393 Default: ``False``
2394
2395 If ``True``, the :class:`~django.middleware.security.SecurityMiddleware` adds
2396 the ``preload`` directive to the :ref:`http-strict-transport-security`
2397 header. It has no effect unless :setting:`SECURE_HSTS_SECONDS` is set to a
2398 non-zero value.
2399
2400 .. setting:: SECURE_HSTS_SECONDS
2401
2402 ``SECURE_HSTS_SECONDS``
2403 -----------------------
2404
2405 Default: ``0``
2406
2407 If set to a non-zero integer value, the
2408 :class:`~django.middleware.security.SecurityMiddleware` sets the
2409 :ref:`http-strict-transport-security` header on all responses that do not
2410 already have it.
2411
2412 .. warning::
2413 Setting this incorrectly can irreversibly (for some time) break your site.
2414 Read the :ref:`http-strict-transport-security` documentation first.
2415
2416 .. setting:: SECURE_PROXY_SSL_HEADER
2417
2418 ``SECURE_PROXY_SSL_HEADER``
2419 ---------------------------
2420
2421 Default: ``None``
2422
2423 A tuple representing an HTTP header/value combination that signifies a request
2424 is secure. This controls the behavior of the request object's ``is_secure()``
2425 method.
2426
2427 By default, ``is_secure()`` determines if a request is secure by confirming
2428 that a requested URL uses ``https://``. This method is important for Django's
2429 CSRF protection, and it may be used by your own code or third-party apps.
2430
2431 If your Django app is behind a proxy, though, the proxy may be "swallowing"
2432 whether the original request uses HTTPS or not. If there is a non-HTTPS
2433 connection between the proxy and Django then ``is_secure()`` would always
2434 return ``False`` -- even for requests that were made via HTTPS by the end user.
2435 In contrast, if there is an HTTPS connection between the proxy and Django then
2436 ``is_secure()`` would always return ``True`` -- even for requests that were
2437 made originally via HTTP.
2438
2439 In this situation, configure your proxy to set a custom HTTP header that tells
2440 Django whether the request came in via HTTPS, and set
2441 ``SECURE_PROXY_SSL_HEADER`` so that Django knows what header to look for.
2442
2443 Set a tuple with two elements -- the name of the header to look for and the
2444 required value. For example::
2445
2446 SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
2447
2448 This tells Django to trust the ``X-Forwarded-Proto`` header that comes from our
2449 proxy and that the request is guaranteed to be secure (i.e., it originally came
2450 in via HTTPS) when:
2451
2452 * the header value is ``'https'``, or
2453 * its initial, leftmost value is ``'https'`` in the case of a comma-separated
2454 list of protocols (e.g. ``'https,http,http'``).
2455
2456 You should *only* set this setting if you control your proxy or have some other
2457 guarantee that it sets/strips this header appropriately.
2458
2459 Note that the header needs to be in the format as used by ``request.META`` --
2460 all caps and likely starting with ``HTTP_``. (Remember, Django automatically
2461 adds ``'HTTP_'`` to the start of x-header names before making the header
2462 available in ``request.META``.)
2463
2464 .. warning::
2465
2466 **Modifying this setting can compromise your site's security. Ensure you
2467 fully understand your setup before changing it.**
2468
2469 Make sure ALL of the following are true before setting this (assuming the
2470 values from the example above):
2471
2472 * Your Django app is behind a proxy.
2473 * Your proxy strips the ``X-Forwarded-Proto`` header from all incoming
2474 requests, even when it contains a comma-separated list of protocols. In
2475 other words, if end users include that header in their requests, the
2476 proxy will discard it.
2477 * Your proxy sets the ``X-Forwarded-Proto`` header and sends it to Django,
2478 but only for requests that originally come in via HTTPS.
2479
2480 If any of those are not true, you should keep this setting set to ``None``
2481 and find another way of determining HTTPS, perhaps via custom middleware.
2482
2483 .. setting:: SECURE_REDIRECT_EXEMPT
2484
2485 ``SECURE_REDIRECT_EXEMPT``
2486 --------------------------
2487
2488 Default: ``[]`` (Empty list)
2489
2490 If a URL path matches a regular expression in this list, the request will not be
2491 redirected to HTTPS. The
2492 :class:`~django.middleware.security.SecurityMiddleware` strips leading slashes
2493 from URL paths, so patterns shouldn't include them, e.g.
2494 ``SECURE_REDIRECT_EXEMPT = [r'^no-ssl/$', …]``. If
2495 :setting:`SECURE_SSL_REDIRECT` is ``False``, this setting has no effect.
2496
2497 .. setting:: SECURE_REFERRER_POLICY
2498
2499 ``SECURE_REFERRER_POLICY``
2500 --------------------------
2501
2502 Default: ``'same-origin'``
2503
2504 If configured, the :class:`~django.middleware.security.SecurityMiddleware` sets
2505 the :ref:`referrer-policy` header on all responses that do not already have it
2506 to the value provided.
2507
2508 .. setting:: SECURE_SSL_HOST
2509
2510 ``SECURE_SSL_HOST``
2511 -------------------
2512
2513 Default: ``None``
2514
2515 If a string (e.g. ``secure.example.com``), all SSL redirects will be directed
2516 to this host rather than the originally-requested host
2517 (e.g. ``www.example.com``). If :setting:`SECURE_SSL_REDIRECT` is ``False``, this
2518 setting has no effect.
2519
2520 .. setting:: SECURE_SSL_REDIRECT
2521
2522 ``SECURE_SSL_REDIRECT``
2523 -----------------------
2524
2525 Default: ``False``
2526
2527 If ``True``, the :class:`~django.middleware.security.SecurityMiddleware`
2528 :ref:`redirects <ssl-redirect>` all non-HTTPS requests to HTTPS (except for
2529 those URLs matching a regular expression listed in
2530 :setting:`SECURE_REDIRECT_EXEMPT`).
2531
2532 .. note::
2533
2534 If turning this to ``True`` causes infinite redirects, it probably means
2535 your site is running behind a proxy and can't tell which requests are secure
2536 and which are not. Your proxy likely sets a header to indicate secure
2537 requests; you can correct the problem by finding out what that header is and
2538 configuring the :setting:`SECURE_PROXY_SSL_HEADER` setting accordingly.
2539
2540 .. setting:: SERIALIZATION_MODULES
2541
2542 ``SERIALIZATION_MODULES``
2543 -------------------------
2544
2545 Default: Not defined
2546
2547 A dictionary of modules containing serializer definitions (provided as
2548 strings), keyed by a string identifier for that serialization type. For
2549 example, to define a YAML serializer, use::
2550
2551 SERIALIZATION_MODULES = {"yaml": "path.to.yaml_serializer"}
2552
2553 .. setting:: SERVER_EMAIL
2554
2555 ``SERVER_EMAIL``
2556 ----------------
2557
2558 Default: ``'root@localhost'``
2559
2560 The email address that error messages come from, such as those sent to
2561 :setting:`ADMINS` and :setting:`MANAGERS`. This address is used in the
2562 ``From:`` header and can take any format valid in the chosen email sending
2563 protocol.
2564
2565 .. admonition:: Why are my emails sent from a different address?
2566
2567 This address is used only for error messages. It is *not* the address that
2568 regular email messages sent with :func:`~django.core.mail.send_mail`
2569 come from; for that, see :setting:`DEFAULT_FROM_EMAIL`.
2570
2571 .. setting:: SHORT_DATE_FORMAT
2572
2573 ``SHORT_DATE_FORMAT``
2574 ---------------------
2575
2576 Default: ``'m/d/Y'`` (e.g. ``12/31/2003``)
2577
2578 An available formatting that can be used for displaying date fields on
2579 templates. Note that the corresponding locale-dictated format has higher
2580 precedence and will be applied instead. See
2581 :tfilter:`allowed date format strings <date>`.
2582
2583 See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATETIME_FORMAT`.
2584
2585 .. setting:: SHORT_DATETIME_FORMAT
2586
2587 ``SHORT_DATETIME_FORMAT``
2588 -------------------------
2589
2590 Default: ``'m/d/Y P'`` (e.g. ``12/31/2003 4 p.m.``)
2591
2592 An available formatting that can be used for displaying datetime fields on
2593 templates. Note that the corresponding locale-dictated format has higher
2594 precedence and will be applied instead. See
2595 :tfilter:`allowed date format strings <date>`.
2596
2597 See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATE_FORMAT`.
2598
2599 .. setting:: SIGNED_COOKIE_LEGACY_SALT_FALLBACK
2600
2601 ``SIGNED_COOKIE_LEGACY_SALT_FALLBACK``
2602 ---------------------------------------
2603
2604 .. versionadded:: 5.2.15
2605
2606 Default: ``True``
2607
2608 Controls whether :meth:`~django.http.HttpRequest.get_signed_cookie` accepts
2609 cookies signed with Django's historical signed-cookie salt derivation based on
2610 ``key + salt``.
2611
2612 Set this to ``False`` to reject those legacy signed cookies and only accept
2613 cookies signed with Django's current unambiguous signed-cookie salt derivation.
2614 This transitional setting will be removed in Django 7.0, when the legacy signed
2615 cookies will no longer be accepted.
2616
2617 .. setting:: SIGNING_BACKEND
2618
2619 ``SIGNING_BACKEND``
2620 -------------------
2621
2622 Default: ``'django.core.signing.TimestampSigner'``
2623
2624 The backend used for signing cookies and other data.
2625
2626 See also the :doc:`/topics/signing` documentation.
2627
2628 .. setting:: SILENCED_SYSTEM_CHECKS
2629
2630 ``SILENCED_SYSTEM_CHECKS``
2631 --------------------------
2632
2633 Default: ``[]`` (Empty list)
2634
2635 A list of identifiers of messages generated by the system check framework
2636 (i.e. ``["models.W001"]``) that you wish to permanently acknowledge and ignore.
2637 Silenced checks will not be output to the console.
2638
2639 See also the :doc:`/ref/checks` documentation.
2640
2641 .. setting:: STORAGES
2642
2643 ``STORAGES``
2644 ------------
2645
2646 Default::
2647
2648 {
2649 "default": {
2650 "BACKEND": "django.core.files.storage.FileSystemStorage",
2651 },
2652 "staticfiles": {
2653 "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
2654 },
2655 }
2656
2657 A dictionary containing the settings for all storages to be used with Django.
2658 It is a nested dictionary whose contents map a storage alias to a dictionary
2659 containing the options for an individual storage.
2660
2661 Storages can have any alias you choose. However, there are two aliases with
2662 special significance:
2663
2664 * ``default`` for :doc:`managing files </topics/files>`.
2665 ``'``:class:`django.core.files.storage.FileSystemStorage`\ ``'`` is the
2666 default storage engine.
2667 * ``staticfiles`` for :doc:`managing static files </ref/contrib/staticfiles>`.
2668 ``'``:class:`django.contrib.staticfiles.storage.StaticFilesStorage`\ ``'`` is
2669 the default storage engine.
2670
2671 The following is an example ``settings.py`` snippet defining a custom file
2672 storage called ``example``::
2673
2674 STORAGES = {
2675 # ...
2676 "example": {
2677 "BACKEND": "django.core.files.storage.FileSystemStorage",
2678 "OPTIONS": {
2679 "location": "/example",
2680 "base_url": "/example/",
2681 },
2682 },
2683 }
2684
2685 ``OPTIONS`` are passed to the ``BACKEND`` on initialization in ``**kwargs``.
2686
2687 A ready-to-use instance of the storage backends can be retrieved from
2688 :data:`django.core.files.storage.storages`. Use a key corresponding to the
2689 backend definition in :setting:`STORAGES`.
2690
2691 .. admonition:: Is my value merged with the default value?
2692
2693 Defining this setting overrides the default value and is *not* merged with
2694 it.
2695
2696 .. setting:: TEMPLATES
2697
2698 ``TEMPLATES``
2699 -------------
2700
2701 Default: ``[]`` (Empty list)
2702
2703 A list containing the settings for all template engines to be used with
2704 Django. Each item of the list is a dictionary containing the options for an
2705 individual engine.
2706
2707 Here's a setup that tells the Django template engine to load templates from the
2708 ``templates`` subdirectory inside each installed application::
2709
2710 TEMPLATES = [
2711 {
2712 "BACKEND": "django.template.backends.django.DjangoTemplates",
2713 "APP_DIRS": True,
2714 },
2715 ]
2716
2717 The following options are available for all backends.
2718
2719 .. setting:: TEMPLATES-BACKEND
2720
2721 ``BACKEND``
2722 ~~~~~~~~~~~
2723
2724 Default: Not defined
2725
2726 The template backend to use. The built-in template backends are:
2727
2728 * ``'django.template.backends.django.DjangoTemplates'``
2729 * ``'django.template.backends.jinja2.Jinja2'``
2730
2731 You can use a template backend that doesn't ship with Django by setting
2732 ``BACKEND`` to a fully-qualified path (i.e. ``'mypackage.whatever.Backend'``).
2733
2734 .. setting:: TEMPLATES-NAME
2735
2736 ``NAME``
2737 ~~~~~~~~
2738
2739 Default: see below
2740
2741 The alias for this particular template engine. It's an identifier that allows
2742 selecting an engine for rendering. Aliases must be unique across all
2743 configured template engines.
2744
2745 It defaults to the name of the module defining the engine class, i.e. the
2746 next to last piece of :setting:`BACKEND <TEMPLATES-BACKEND>`, when it isn't
2747 provided. For example if the backend is ``'mypackage.whatever.Backend'`` then
2748 its default name is ``'whatever'``.
2749
2750 .. setting:: TEMPLATES-DIRS
2751
2752 ``DIRS``
2753 ~~~~~~~~
2754
2755 Default: ``[]`` (Empty list)
2756
2757 Directories where the engine should look for template source files, in search
2758 order.
2759
2760 .. setting:: TEMPLATES-APP_DIRS
2761
2762 ``APP_DIRS``
2763 ~~~~~~~~~~~~
2764
2765 Default: ``False``
2766
2767 Whether the engine should look for template source files inside installed
2768 applications.
2769
2770 .. note::
2771
2772 The default :file:`settings.py` file created by :djadmin:`django-admin
2773 startproject <startproject>` sets ``'APP_DIRS': True``.
2774
2775 .. setting:: TEMPLATES-OPTIONS
2776
2777 ``OPTIONS``
2778 ~~~~~~~~~~~
2779
2780 Default: ``{}`` (Empty dict)
2781
2782 Extra parameters to pass to the template backend. Available parameters vary
2783 depending on the template backend. See
2784 :class:`~django.template.backends.django.DjangoTemplates` and
2785 :class:`~django.template.backends.jinja2.Jinja2` for the options of the
2786 built-in backends.
2787
2788 .. setting:: TEST_RUNNER
2789
2790 ``TEST_RUNNER``
2791 ---------------
2792
2793 Default: ``'django.test.runner.DiscoverRunner'``
2794
2795 The name of the class to use for starting the test suite. See
2796 :ref:`other-testing-frameworks`.
2797
2798 .. setting:: TEST_NON_SERIALIZED_APPS
2799
2800 ``TEST_NON_SERIALIZED_APPS``
2801 ----------------------------
2802
2803 Default: ``[]`` (Empty list)
2804
2805 In order to restore the database state between tests for
2806 ``TransactionTestCase``\s and database backends without transactions, Django
2807 will :ref:`serialize the contents of all apps <test-case-serialized-rollback>`
2808 when it starts the test run so it can then reload from that copy before running
2809 tests that need it.
2810
2811 This slows down the startup time of the test runner; if you have apps that
2812 you know don't need this feature, you can add their full names in here (e.g.
2813 ``'django.contrib.contenttypes'``) to exclude them from this serialization
2814 process.
2815
2816 .. setting:: THOUSAND_SEPARATOR
2817
2818 ``THOUSAND_SEPARATOR``
2819 ----------------------
2820
2821 Default: ``','`` (Comma)
2822
2823 Default thousand separator used when formatting numbers. This setting is
2824 used only when :setting:`USE_THOUSAND_SEPARATOR` is ``True`` and
2825 :setting:`NUMBER_GROUPING` is greater than ``0``.
2826
2827 Note that the locale-dictated format has higher precedence and will be applied
2828 instead.
2829
2830 See also :setting:`NUMBER_GROUPING`, :setting:`DECIMAL_SEPARATOR` and
2831 :setting:`USE_THOUSAND_SEPARATOR`.
2832
2833 .. setting:: TIME_FORMAT
2834
2835 ``TIME_FORMAT``
2836 ---------------
2837
2838 Default: ``'P'`` (e.g. ``4 p.m.``)
2839
2840 The default formatting to use for displaying time fields in any part of the
2841 system. Note that the locale-dictated format has higher precedence and will be
2842 applied instead. See :tfilter:`allowed date format strings <date>`.
2843
2844 See also :setting:`DATE_FORMAT` and :setting:`DATETIME_FORMAT`.
2845
2846 .. setting:: TIME_INPUT_FORMATS
2847
2848 ``TIME_INPUT_FORMATS``
2849 ----------------------
2850
2851 Default::
2852
2853 [
2854 "%H:%M:%S", # '14:30:59'
2855 "%H:%M:%S.%f", # '14:30:59.000200'
2856 "%H:%M", # '14:30'
2857 ]
2858
2859 A list of formats that will be accepted when inputting data on a time field.
2860 Formats will be tried in order, using the first valid one. Note that these
2861 format strings use Python's :ref:`datetime module syntax
2862 <strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
2863 template filter.
2864
2865 The locale-dictated format has higher precedence and will be applied instead.
2866
2867 See also :setting:`DATE_INPUT_FORMATS` and :setting:`DATETIME_INPUT_FORMATS`.
2868
2869 .. setting:: TIME_ZONE
2870
2871 ``TIME_ZONE``
2872 -------------
2873
2874 Default: ``'America/Chicago'``
2875
2876 A string representing the time zone for this installation. See the `list of
2877 time zones`_.
2878
2879 .. note::
2880 Since Django was first released with the :setting:`TIME_ZONE` set to
2881 ``'America/Chicago'``, the global setting (used if nothing is defined in
2882 your project's ``settings.py``) remains ``'America/Chicago'`` for backwards
2883 compatibility. New project templates default to ``'UTC'``.
2884
2885 Note that this isn't necessarily the time zone of the server. For example, one
2886 server may serve multiple Django-powered sites, each with a separate time zone
2887 setting.
2888
2889 When :setting:`USE_TZ` is ``False``, this is the time zone in which Django
2890 will store all datetimes. When :setting:`USE_TZ` is ``True``, this is the
2891 default time zone that Django will use to display datetimes in templates and
2892 to interpret datetimes entered in forms.
2893
2894 On Unix environments (where :func:`time.tzset` is implemented), Django sets the
2895 ``os.environ['TZ']`` variable to the time zone you specify in the
2896 :setting:`TIME_ZONE` setting. Thus, all your views and models will
2897 automatically operate in this time zone. However, Django won't set the ``TZ``
2898 environment variable if you're using the manual configuration option as
2899 described in :ref:`manually configuring settings
2900 <settings-without-django-settings-module>`. If Django doesn't set the ``TZ``
2901 environment variable, it's up to you to ensure your processes are running in
2902 the correct environment.
2903
2904 .. note::
2905 Django cannot reliably use alternate time zones in a Windows environment.
2906 If you're running Django on Windows, :setting:`TIME_ZONE` must be set to
2907 match the system time zone.
2908
2909 .. _list of time zones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
2910
2911 .. setting:: USE_I18N
2912
2913 ``USE_I18N``
2914 ------------
2915
2916 Default: ``True``
2917
2918 A boolean that specifies whether Django's translation system should be enabled.
2919 This provides a way to turn it off, for performance. If this is set to
2920 ``False``, Django will make some optimizations so as not to load the
2921 translation machinery.
2922
2923 See also :setting:`LANGUAGE_CODE` and :setting:`USE_TZ`.
2924
2925 .. note::
2926
2927 The default :file:`settings.py` file created by :djadmin:`django-admin
2928 startproject <startproject>` includes ``USE_I18N = True`` for convenience.
2929
2930 .. setting:: USE_THOUSAND_SEPARATOR
2931
2932 ``USE_THOUSAND_SEPARATOR``
2933 --------------------------
2934
2935 Default: ``False``
2936
2937 A boolean that specifies whether to display numbers using a thousand separator.
2938 When set to ``True``, Django will format numbers using the
2939 :setting:`NUMBER_GROUPING` and :setting:`THOUSAND_SEPARATOR` settings. The
2940 latter two settings may also be dictated by the locale, which takes precedence.
2941
2942 See also :setting:`DECIMAL_SEPARATOR`, :setting:`NUMBER_GROUPING` and
2943 :setting:`THOUSAND_SEPARATOR`.
2944
2945 .. setting:: USE_TZ
2946
2947 ``USE_TZ``
2948 ----------
2949
2950 Default: ``True``
2951
2952 A boolean that specifies if datetimes will be timezone-aware by default or not.
2953 If this is set to ``True``, Django will use timezone-aware datetimes internally.
2954
2955 When ``USE_TZ`` is False, Django will use naive datetimes in local time, except
2956 when parsing ISO 8601 formatted strings, where timezone information will always
2957 be retained if present.
2958
2959 See also :setting:`TIME_ZONE` and :setting:`USE_I18N`.
2960
2961 .. setting:: USE_X_FORWARDED_HOST
2962
2963 ``USE_X_FORWARDED_HOST``
2964 ------------------------
2965
2966 Default: ``False``
2967
2968 A boolean that specifies whether to use the ``X-Forwarded-Host`` header in
2969 preference to the ``Host`` header. This should only be enabled if a proxy
2970 which sets this header is in use.
2971
2972 This setting takes priority over :setting:`USE_X_FORWARDED_PORT`. Per
2973 :rfc:`7239#section-5.3`, the ``X-Forwarded-Host`` header can include the port
2974 number, in which case you shouldn't use :setting:`USE_X_FORWARDED_PORT`.
2975
2976 .. setting:: USE_X_FORWARDED_PORT
2977
2978 ``USE_X_FORWARDED_PORT``
2979 ------------------------
2980
2981 Default: ``False``
2982
2983 A boolean that specifies whether to use the ``X-Forwarded-Port`` header in
2984 preference to the ``SERVER_PORT`` ``META`` variable. This should only be
2985 enabled if a proxy which sets this header is in use.
2986
2987 :setting:`USE_X_FORWARDED_HOST` takes priority over this setting.
2988
2989 .. setting:: WSGI_APPLICATION
2990
2991 ``WSGI_APPLICATION``
2992 --------------------
2993
2994 Default: ``None``
2995
2996 The full Python path of the WSGI application object that Django's built-in
2997 servers (e.g. :djadmin:`runserver`) will use. The :djadmin:`django-admin
2998 startproject <startproject>` management command will create a standard
2999 ``wsgi.py`` file with an ``application`` callable in it, and point this setting
3000 to that ``application``.
3001
3002 If not set, the return value of ``django.core.wsgi.get_wsgi_application()``
3003 will be used. In this case, the behavior of :djadmin:`runserver` will be
3004 identical to previous Django versions.
3005
3006 .. setting:: YEAR_MONTH_FORMAT
3007
3008 ``YEAR_MONTH_FORMAT``
3009 ---------------------
3010
3011 Default: ``'F Y'``
3012
3013 The default formatting to use for date fields on Django admin change-list
3014 pages -- and, possibly, by other parts of the system -- in cases when only the
3015 year and month are displayed.
3016
3017 For example, when a Django admin change-list page is being filtered by a date
3018 drilldown, the header for a given month displays the month and the year.
3019 Different locales have different formats. For example, U.S. English would say
3020 "January 2006," whereas another locale might say "2006/January."
3021
3022 Note that the corresponding locale-dictated format has higher precedence and
3023 will be applied instead.
3024
3025 See :tfilter:`allowed date format strings <date>`. See also
3026 :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT`
3027 and :setting:`MONTH_DAY_FORMAT`.
3028
3029 .. setting:: X_FRAME_OPTIONS
3030
3031 ``X_FRAME_OPTIONS``
3032 -------------------
3033
3034 Default: ``'DENY'``
3035
3036 The default value for the X-Frame-Options header used by
3037 :class:`~django.middleware.clickjacking.XFrameOptionsMiddleware`. See the
3038 :doc:`clickjacking protection </ref/clickjacking/>` documentation.
3039
3040 Auth
3041 ====
3042
3043 Settings for :mod:`django.contrib.auth`.
3044
3045 .. setting:: AUTHENTICATION_BACKENDS
3046
3047 ``AUTHENTICATION_BACKENDS``
3048 ---------------------------
3049
3050 Default: ``['django.contrib.auth.backends.ModelBackend']``
3051
3052 A list of authentication backend classes (as strings) to use when attempting to
3053 authenticate a user. See the :ref:`authentication backends documentation
3054 <authentication-backends>` for details.
3055
3056 .. setting:: AUTH_USER_MODEL
3057
3058 ``AUTH_USER_MODEL``
3059 -------------------
3060
3061 Default: ``'auth.User'``
3062
3063 The model to use to represent a User. See :ref:`auth-custom-user`.
3064
3065 .. warning::
3066 You cannot change the AUTH_USER_MODEL setting during the lifetime of
3067 a project (i.e. once you have made and migrated models that depend on it)
3068 without serious effort. It is intended to be set at the project start,
3069 and the model it refers to must be available in the first migration of
3070 the app that it lives in.
3071 See :ref:`auth-custom-user` for more details.
3072
3073 .. setting:: LOGIN_REDIRECT_URL
3074
3075 ``LOGIN_REDIRECT_URL``
3076 ----------------------
3077
3078 Default: ``'/accounts/profile/'``
3079
3080 The URL or :ref:`named URL pattern <naming-url-patterns>` where requests are
3081 redirected after login when the :class:`~django.contrib.auth.views.LoginView`
3082 doesn't get a ``next`` GET parameter.
3083
3084 .. setting:: LOGIN_URL
3085
3086 ``LOGIN_URL``
3087 -------------
3088
3089 Default: ``'/accounts/login/'``
3090
3091 The URL or :ref:`named URL pattern <naming-url-patterns>` where requests are
3092 redirected for login when using the
3093 :func:`~django.contrib.auth.decorators.login_required` decorator,
3094 :class:`~django.contrib.auth.mixins.LoginRequiredMixin`,
3095 :class:`~django.contrib.auth.mixins.AccessMixin`, or when
3096 :class:`~django.contrib.auth.middleware.LoginRequiredMiddleware` is installed.
3097
3098 .. setting:: LOGOUT_REDIRECT_URL
3099
3100 ``LOGOUT_REDIRECT_URL``
3101 -----------------------
3102
3103 Default: ``None``
3104
3105 The URL or :ref:`named URL pattern <naming-url-patterns>` where requests are
3106 redirected after logout if :class:`~django.contrib.auth.views.LogoutView`
3107 doesn't have a ``next_page`` attribute.
3108
3109 If ``None``, no redirect will be performed and the logout view will be
3110 rendered.
3111
3112 .. setting:: PASSWORD_RESET_TIMEOUT
3113
3114 ``PASSWORD_RESET_TIMEOUT``
3115 --------------------------
3116
3117 Default: ``259200`` (3 days, in seconds)
3118
3119 The number of seconds a password reset link is valid for.
3120
3121 Used by the :class:`~django.contrib.auth.views.PasswordResetConfirmView`.
3122
3123 .. note::
3124
3125 Reducing the value of this timeout doesn't make any difference to the
3126 ability of an attacker to brute-force a password reset token. Tokens are
3127 designed to be safe from brute-forcing without any timeout.
3128
3129 This timeout exists to protect against some unlikely attack scenarios, such
3130 as someone gaining access to email archives that may contain old, unused
3131 password reset tokens.
3132
3133 .. setting:: PASSWORD_HASHERS
3134
3135 ``PASSWORD_HASHERS``
3136 --------------------
3137
3138 See :ref:`auth_password_storage`.
3139
3140 Default::
3141
3142 [
3143 "django.contrib.auth.hashers.PBKDF2PasswordHasher",
3144 "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",
3145 "django.contrib.auth.hashers.Argon2PasswordHasher",
3146 "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",
3147 "django.contrib.auth.hashers.ScryptPasswordHasher",
3148 ]
3149
3150 .. setting:: AUTH_PASSWORD_VALIDATORS
3151
3152 ``AUTH_PASSWORD_VALIDATORS``
3153 ----------------------------
3154
3155 Default: ``[]`` (Empty list)
3156
3157 The list of validators that are used to check the strength of user's passwords.
3158 See :ref:`password-validation` for more details. By default, no validation is
3159 performed and all passwords are accepted.
3160
3161 .. _settings-messages:
3162
3163 Messages
3164 ========
3165
3166 Settings for :mod:`django.contrib.messages`.
3167
3168 .. setting:: MESSAGE_LEVEL
3169
3170 ``MESSAGE_LEVEL``
3171 -----------------
3172
3173 Default: ``messages.INFO``
3174
3175 Sets the minimum message level that will be recorded by the messages
3176 framework. See :ref:`message levels <message-level>` for more details.
3177
3178 .. admonition:: Avoiding circular imports
3179
3180 If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
3181 the built-in constants, you must import the constants module directly to
3182 avoid the potential for circular imports, e.g.::
3183
3184 from django.contrib.messages import constants as message_constants
3185
3186 MESSAGE_LEVEL = message_constants.DEBUG
3187
3188 If desired, you may specify the numeric values for the constants directly
3189 according to the values in the above :ref:`constants table
3190 <message-level-constants>`.
3191
3192 .. setting:: MESSAGE_STORAGE
3193
3194 ``MESSAGE_STORAGE``
3195 -------------------
3196
3197 Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'``
3198
3199 Controls where Django stores message data. Valid values are:
3200
3201 * ``'django.contrib.messages.storage.fallback.FallbackStorage'``
3202 * ``'django.contrib.messages.storage.session.SessionStorage'``
3203 * ``'django.contrib.messages.storage.cookie.CookieStorage'``
3204
3205 See :ref:`message storage backends <message-storage-backends>` for more details.
3206
3207 The backends that use cookies --
3208 :class:`~django.contrib.messages.storage.cookie.CookieStorage` and
3209 :class:`~django.contrib.messages.storage.fallback.FallbackStorage` --
3210 use the value of :setting:`SESSION_COOKIE_DOMAIN`, :setting:`SESSION_COOKIE_SECURE`
3211 and :setting:`SESSION_COOKIE_HTTPONLY` when setting their cookies.
3212
3213 .. setting:: MESSAGE_TAGS
3214
3215 ``MESSAGE_TAGS``
3216 ----------------
3217
3218 Default::
3219
3220 {
3221 messages.DEBUG: "debug",
3222 messages.INFO: "info",
3223 messages.SUCCESS: "success",
3224 messages.WARNING: "warning",
3225 messages.ERROR: "error",
3226 }
3227
3228 This sets the mapping of message level to message tag, which is typically
3229 rendered as a CSS class in HTML. If you specify a value, it will extend
3230 the default. This means you only have to specify those values which you need
3231 to override. See :ref:`message-displaying` above for more details.
3232
3233 .. admonition:: Avoiding circular imports
3234
3235 If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
3236 the built-in constants, you must import the ``constants`` module directly to
3237 avoid the potential for circular imports, e.g.::
3238
3239 from django.contrib.messages import constants as message_constants
3240
3241 MESSAGE_TAGS = {message_constants.INFO: ""}
3242
3243 If desired, you may specify the numeric values for the constants directly
3244 according to the values in the above :ref:`constants table
3245 <message-level-constants>`.
3246
3247 .. _settings-sessions:
3248
3249 Sessions
3250 ========
3251
3252 Settings for :mod:`django.contrib.sessions`.
3253
3254 .. setting:: SESSION_CACHE_ALIAS
3255
3256 ``SESSION_CACHE_ALIAS``
3257 -----------------------
3258
3259 Default: ``'default'``
3260
3261 If you're using :ref:`cache-based session storage <cached-sessions-backend>`,
3262 this selects the cache to use.
3263
3264 .. setting:: SESSION_COOKIE_AGE
3265
3266 ``SESSION_COOKIE_AGE``
3267 ----------------------
3268
3269 Default: ``1209600`` (2 weeks, in seconds)
3270
3271 The age of session cookies, in seconds.
3272
3273 .. setting:: SESSION_COOKIE_DOMAIN
3274
3275 ``SESSION_COOKIE_DOMAIN``
3276 -------------------------
3277
3278 Default: ``None``
3279
3280 The domain to use for session cookies. Set this to a string such as
3281 ``"example.com"`` for cross-domain cookies, or use ``None`` for a standard
3282 domain cookie.
3283
3284 To use cross-domain cookies with :setting:`CSRF_USE_SESSIONS`, you must include
3285 a leading dot (e.g. ``".example.com"``) to accommodate the CSRF middleware's
3286 referer checking.
3287
3288 Be cautious when updating this setting on a production site. If you update
3289 this setting to enable cross-domain cookies on a site that previously used
3290 standard domain cookies, existing user cookies will be set to the old
3291 domain. This may result in them being unable to log in as long as these cookies
3292 persist.
3293
3294 This setting also affects cookies set by :mod:`django.contrib.messages`.
3295
3296 .. setting:: SESSION_COOKIE_HTTPONLY
3297
3298 ``SESSION_COOKIE_HTTPONLY``
3299 ---------------------------
3300
3301 Default: ``True``
3302
3303 Whether to use ``HttpOnly`` flag on the session cookie. If this is set to
3304 ``True``, client-side JavaScript will not be able to access the session
3305 cookie.
3306
3307 HttpOnly_ is a flag included in a Set-Cookie HTTP response header. It's part of
3308 the :rfc:`6265#section-4.1.2.6` standard for cookies and can be a useful way to
3309 mitigate the risk of a client-side script accessing the protected cookie data.
3310
3311 This makes it less trivial for an attacker to escalate a cross-site scripting
3312 vulnerability into full hijacking of a user's session. There aren't many good
3313 reasons for turning this off. Your code shouldn't read session cookies from
3314 JavaScript.
3315
3316 .. _HttpOnly: https://owasp.org/www-community/HttpOnly
3317
3318 .. setting:: SESSION_COOKIE_NAME
3319
3320 ``SESSION_COOKIE_NAME``
3321 -----------------------
3322
3323 Default: ``'sessionid'``
3324
3325 The name of the cookie to use for sessions. This can be whatever you want
3326 (as long as it's different from the other cookie names in your application).
3327
3328 .. setting:: SESSION_COOKIE_PATH
3329
3330 ``SESSION_COOKIE_PATH``
3331 -----------------------
3332
3333 Default: ``'/'``
3334
3335 The path set on the session cookie. This should either match the URL path of your
3336 Django installation or be parent of that path.
3337
3338 This is useful if you have multiple Django instances running under the same
3339 hostname. They can use different cookie paths, and each instance will only see
3340 its own session cookie.
3341
3342 .. setting:: SESSION_COOKIE_SAMESITE
3343
3344 ``SESSION_COOKIE_SAMESITE``
3345 ---------------------------
3346
3347 Default: ``'Lax'``
3348
3349 The value of the `SameSite`_ flag on the session cookie. This flag prevents the
3350 cookie from being sent in cross-site requests thus preventing CSRF attacks and
3351 making some methods of stealing session cookie impossible.
3352
3353 Possible values for the setting are:
3354
3355 * ``'Strict'``: prevents the cookie from being sent by the browser to the
3356 target site in all cross-site browsing context, even when following a regular
3357 link.
3358
3359 For example, for a GitHub-like website this would mean that if a logged-in
3360 user follows a link to a private GitHub project posted on a corporate
3361 discussion forum or email, GitHub will not receive the session cookie and the
3362 user won't be able to access the project. A bank website, however, most
3363 likely doesn't want to allow any transactional pages to be linked from
3364 external sites so the ``'Strict'`` flag would be appropriate.
3365
3366 * ``'Lax'`` (default): provides a balance between security and usability for
3367 websites that want to maintain user's logged-in session after the user
3368 arrives from an external link.
3369
3370 In the GitHub scenario, the session cookie would be allowed when following a
3371 regular link from an external website and be blocked in CSRF-prone request
3372 methods (e.g. ``POST``).
3373
3374 * ``'None'`` (string): the session cookie will be sent with all same-site and
3375 cross-site requests.
3376
3377 * ``False``: disables the flag.
3378
3379 .. note::
3380
3381 Modern browsers provide a more secure default policy for the ``SameSite``
3382 flag and will assume ``Lax`` for cookies without an explicit value set.
3383
3384 .. _SameSite: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value
3385
3386 .. setting:: SESSION_COOKIE_SECURE
3387
3388 ``SESSION_COOKIE_SECURE``
3389 -------------------------
3390
3391 Default: ``False``
3392
3393 Whether to use a secure cookie for the session cookie. If this is set to
3394 ``True``, the cookie will be marked as "secure", which means browsers may
3395 ensure that the cookie is only sent under an HTTPS connection.
3396
3397 Leaving this setting off isn't a good idea because an attacker could capture an
3398 unencrypted session cookie with a packet sniffer and use the cookie to hijack
3399 the user's session.
3400
3401 .. setting:: SESSION_ENGINE
3402
3403 ``SESSION_ENGINE``
3404 ------------------
3405
3406 Default: ``'django.contrib.sessions.backends.db'``
3407
3408 Controls where Django stores session data. Included engines are:
3409
3410 * ``'django.contrib.sessions.backends.db'``
3411 * ``'django.contrib.sessions.backends.file'``
3412 * ``'django.contrib.sessions.backends.cache'``
3413 * ``'django.contrib.sessions.backends.cached_db'``
3414 * ``'django.contrib.sessions.backends.signed_cookies'``
3415
3416 See :ref:`configuring-sessions` for more details.
3417
3418 .. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE
3419
3420 ``SESSION_EXPIRE_AT_BROWSER_CLOSE``
3421 -----------------------------------
3422
3423 Default: ``False``
3424
3425 Whether to expire the session when the user closes their browser. See
3426 :ref:`browser-length-vs-persistent-sessions`.
3427
3428 .. setting:: SESSION_FILE_PATH
3429
3430 ``SESSION_FILE_PATH``
3431 ---------------------
3432
3433 Default: ``None``
3434
3435 If you're using file-based session storage, this sets the directory in
3436 which Django will store session data. When the default value (``None``) is
3437 used, Django will use the standard temporary directory for the system.
3438
3439
3440 .. setting:: SESSION_SAVE_EVERY_REQUEST
3441
3442 ``SESSION_SAVE_EVERY_REQUEST``
3443 ------------------------------
3444
3445 Default: ``False``
3446
3447 Whether to save the session data on every request. If this is ``False``
3448 (default), then the session data will only be saved if it has been modified --
3449 that is, if any of its dictionary values have been assigned or deleted. Empty
3450 sessions won't be created, even if this setting is active.
3451
3452 .. setting:: SESSION_SERIALIZER
3453
3454 ``SESSION_SERIALIZER``
3455 ----------------------
3456
3457 Default: ``'django.contrib.sessions.serializers.JSONSerializer'``
3458
3459 Full import path of a serializer class to use for serializing session data.
3460 Included serializer is:
3461
3462 * ``'django.contrib.sessions.serializers.JSONSerializer'``
3463
3464 See :ref:`session_serialization` for details.
3465
3466 Sites
3467 =====
3468
3469 Settings for :mod:`django.contrib.sites`.
3470
3471 .. setting:: SITE_ID
3472
3473 ``SITE_ID``
3474 -----------
3475
3476 Default: Not defined
3477
3478 The ID, as an integer, of the current site in the ``django_site`` database
3479 table. This is used so that application data can hook into specific sites
3480 and a single database can manage content for multiple sites.
3481
3482
3483 .. _settings-staticfiles:
3484
3485 Static Files
3486 ============
3487
3488 Settings for :mod:`django.contrib.staticfiles`.
3489
3490 .. setting:: STATIC_ROOT
3491
3492 ``STATIC_ROOT``
3493 ---------------
3494
3495 Default: ``None``
3496
3497 The absolute path to the directory where :djadmin:`collectstatic` will collect
3498 static files for deployment.
3499
3500 Example: ``"/var/www/example.com/static/"``
3501
3502 If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
3503 (as in the default project template), the :djadmin:`collectstatic` management
3504 command will collect static files into this directory. See the how-to on
3505 :doc:`managing static files</howto/static-files/index>` for more details about
3506 usage.
3507
3508 .. warning::
3509
3510 This should be an initially empty destination directory for collecting
3511 your static files from their permanent locations into one directory for
3512 ease of deployment; it is **not** a place to store your static files
3513 permanently. You should do that in directories that will be found by
3514 :doc:`staticfiles</ref/contrib/staticfiles>`’s
3515 :setting:`finders<STATICFILES_FINDERS>`, which by default, are
3516 ``'static/'`` app sub-directories and any directories you include in
3517 :setting:`STATICFILES_DIRS`).
3518
3519 .. setting:: STATIC_URL
3520
3521 ``STATIC_URL``
3522 --------------
3523
3524 Default: ``None``
3525
3526 URL to use when referring to static files located in :setting:`STATIC_ROOT`.
3527
3528 Example: ``"static/"`` or ``"https://static.example.com/"``
3529
3530 If not ``None``, this will be used as the base path for
3531 :ref:`asset definitions<form-asset-paths>` (the ``Media`` class) and the
3532 :doc:`staticfiles app</ref/contrib/staticfiles>`.
3533
3534 It must end in a slash if set to a non-empty value.
3535
3536 You may need to :ref:`configure these files to be served in development
3537 <serving-static-files-in-development>` and will definitely need to do so
3538 :doc:`in production </howto/static-files/deployment>`.
3539
3540 .. note::
3541
3542 If :setting:`STATIC_URL` is a relative path, then it will be prefixed by
3543 the server-provided value of ``SCRIPT_NAME`` (or ``/`` if not set). This
3544 makes it easier to serve a Django application in a subpath without adding
3545 an extra configuration to the settings.
3546
3547 .. setting:: STATICFILES_DIRS
3548
3549 ``STATICFILES_DIRS``
3550 --------------------
3551
3552 Default: ``[]`` (Empty list)
3553
3554 This setting defines the additional locations the staticfiles app will traverse
3555 if the ``FileSystemFinder`` finder is enabled, e.g. if you use the
3556 :djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
3557 static file serving view.
3558
3559 This should be set to a list of strings that contain full paths to
3560 your additional files directory(ies) e.g.::
3561
3562 STATICFILES_DIRS = [
3563 "/home/special.polls.com/polls/static",
3564 "/home/polls.com/polls/static",
3565 "/opt/webfiles/common",
3566 ]
3567
3568 Note that these paths should use Unix-style forward slashes, even on Windows
3569 (e.g. ``"C:/Users/user/mysite/extra_static_content"``).
3570
3571 .. _staticfiles-dirs-prefixes:
3572
3573 Prefixes (optional)
3574 ~~~~~~~~~~~~~~~~~~~
3575
3576 In case you want to refer to files in one of the locations with an additional
3577 namespace, you can **optionally** provide a prefix as ``(prefix, path)``
3578 tuples, e.g.::
3579
3580 STATICFILES_DIRS = [
3581 # ...
3582 ("downloads", "/opt/webfiles/stats"),
3583 ]
3584
3585 For example, assuming you have :setting:`STATIC_URL` set to ``'static/'``, the
3586 :djadmin:`collectstatic` management command would collect the "stats" files
3587 in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
3588
3589 This would allow you to refer to the local file
3590 ``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
3591 ``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.:
3592
3593 .. code-block:: html+django
3594
3595 <a href="{% static 'downloads/polls_20101022.tar.gz' %}">
3596
3597 .. setting:: STATICFILES_FINDERS
3598
3599 ``STATICFILES_FINDERS``
3600 -----------------------
3601
3602 Default::
3603
3604 [
3605 "django.contrib.staticfiles.finders.FileSystemFinder",
3606 "django.contrib.staticfiles.finders.AppDirectoriesFinder",
3607 ]
3608
3609 The list of finder backends that know how to find static files in
3610 various locations.
3611
3612 The default will find files stored in the :setting:`STATICFILES_DIRS` setting
3613 (using ``django.contrib.staticfiles.finders.FileSystemFinder``) and in a
3614 ``static`` subdirectory of each app (using
3615 ``django.contrib.staticfiles.finders.AppDirectoriesFinder``). If multiple
3616 files with the same name are present, the first file that is found will be
3617 used.
3618
3619 One finder is disabled by default:
3620 ``django.contrib.staticfiles.finders.DefaultStorageFinder``. If added to
3621 your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
3622 the default file storage as defined by the ``default`` key in the
3623 :setting:`STORAGES` setting.
3624
3625 .. note::
3626
3627 When using the ``AppDirectoriesFinder`` finder, make sure your apps
3628 can be found by staticfiles by adding the app to the
3629 :setting:`INSTALLED_APPS` setting of your site.
3630
3631 Static file finders are currently considered a private interface, and this
3632 interface is thus undocumented.
3633
3634 Core Settings Topical Index
3635 ===========================
3636
3637 Cache
3638 -----
3639 * :setting:`CACHES`
3640 * :setting:`CACHE_MIDDLEWARE_ALIAS`
3641 * :setting:`CACHE_MIDDLEWARE_KEY_PREFIX`
3642 * :setting:`CACHE_MIDDLEWARE_SECONDS`
3643
3644 Database
3645 --------
3646 * :setting:`DATABASES`
3647 * :setting:`DATABASE_ROUTERS`
3648 * :setting:`DEFAULT_INDEX_TABLESPACE`
3649 * :setting:`DEFAULT_TABLESPACE`
3650
3651 Debugging
3652 ---------
3653 * :setting:`DEBUG`
3654 * :setting:`DEBUG_PROPAGATE_EXCEPTIONS`
3655
3656 Email
3657 -----
3658 * :setting:`ADMINS`
3659 * :setting:`DEFAULT_CHARSET`
3660 * :setting:`DEFAULT_FROM_EMAIL`
3661 * :setting:`EMAIL_BACKEND`
3662 * :setting:`EMAIL_FILE_PATH`
3663 * :setting:`EMAIL_HOST`
3664 * :setting:`EMAIL_HOST_PASSWORD`
3665 * :setting:`EMAIL_HOST_USER`
3666 * :setting:`EMAIL_PORT`
3667 * :setting:`EMAIL_SSL_CERTFILE`
3668 * :setting:`EMAIL_SSL_KEYFILE`
3669 * :setting:`EMAIL_SUBJECT_PREFIX`
3670 * :setting:`EMAIL_TIMEOUT`
3671 * :setting:`EMAIL_USE_LOCALTIME`
3672 * :setting:`EMAIL_USE_SSL`
3673 * :setting:`EMAIL_USE_TLS`
3674 * :setting:`MANAGERS`
3675 * :setting:`SERVER_EMAIL`
3676
3677 Error reporting
3678 ---------------
3679 * :setting:`DEFAULT_EXCEPTION_REPORTER`
3680 * :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER`
3681 * :setting:`IGNORABLE_404_URLS`
3682 * :setting:`MANAGERS`
3683 * :setting:`SILENCED_SYSTEM_CHECKS`
3684
3685 .. _file-upload-settings:
3686
3687 File uploads
3688 ------------
3689 * :setting:`FILE_UPLOAD_HANDLERS`
3690 * :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`
3691 * :setting:`FILE_UPLOAD_PERMISSIONS`
3692 * :setting:`FILE_UPLOAD_TEMP_DIR`
3693 * :setting:`MEDIA_ROOT`
3694 * :setting:`MEDIA_URL`
3695 * :setting:`STORAGES`
3696
3697 Forms
3698 -----
3699 * :setting:`FORM_RENDERER`
3700 * :setting:`FORMS_URLFIELD_ASSUME_HTTPS`
3701
3702 Globalization (``i18n``/``l10n``)
3703 ---------------------------------
3704
3705 .. _settings-i18n:
3706
3707 Internationalization (``i18n``)
3708 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3709
3710 * :setting:`FIRST_DAY_OF_WEEK`
3711 * :setting:`FORMAT_MODULE_PATH`
3712 * :setting:`LANGUAGE_COOKIE_AGE`
3713 * :setting:`LANGUAGE_COOKIE_DOMAIN`
3714 * :setting:`LANGUAGE_COOKIE_HTTPONLY`
3715 * :setting:`LANGUAGE_COOKIE_NAME`
3716 * :setting:`LANGUAGE_COOKIE_PATH`
3717 * :setting:`LANGUAGE_COOKIE_SAMESITE`
3718 * :setting:`LANGUAGE_COOKIE_SECURE`
3719 * :setting:`LANGUAGES`
3720 * :setting:`LANGUAGES_BIDI`
3721 * :setting:`LOCALE_PATHS`
3722 * :setting:`TIME_ZONE`
3723 * :setting:`USE_I18N`
3724 * :setting:`USE_TZ`
3725
3726 .. _settings-l10n:
3727
3728 Localization (``l10n``)
3729 ~~~~~~~~~~~~~~~~~~~~~~~
3730
3731 * :setting:`DATE_FORMAT`
3732 * :setting:`DATE_INPUT_FORMATS`
3733 * :setting:`DATETIME_FORMAT`
3734 * :setting:`DATETIME_INPUT_FORMATS`
3735 * :setting:`DECIMAL_SEPARATOR`
3736 * :setting:`LANGUAGE_CODE`
3737 * :setting:`MONTH_DAY_FORMAT`
3738 * :setting:`NUMBER_GROUPING`
3739 * :setting:`SHORT_DATE_FORMAT`
3740 * :setting:`SHORT_DATETIME_FORMAT`
3741 * :setting:`THOUSAND_SEPARATOR`
3742 * :setting:`TIME_FORMAT`
3743 * :setting:`TIME_INPUT_FORMATS`
3744 * :setting:`USE_THOUSAND_SEPARATOR`
3745 * :setting:`YEAR_MONTH_FORMAT`
3746
3747 HTTP
3748 ----
3749 * :setting:`DATA_UPLOAD_MAX_MEMORY_SIZE`
3750 * :setting:`DATA_UPLOAD_MAX_NUMBER_FIELDS`
3751 * :setting:`DATA_UPLOAD_MAX_NUMBER_FILES`
3752 * :setting:`DEFAULT_CHARSET`
3753 * :setting:`DISALLOWED_USER_AGENTS`
3754 * :setting:`FORCE_SCRIPT_NAME`
3755 * :setting:`INTERNAL_IPS`
3756 * :setting:`MIDDLEWARE`
3757 * Security
3758
3759 * :setting:`SECURE_CONTENT_TYPE_NOSNIFF`
3760 * :setting:`SECURE_CROSS_ORIGIN_OPENER_POLICY`
3761 * :setting:`SECURE_HSTS_INCLUDE_SUBDOMAINS`
3762 * :setting:`SECURE_HSTS_PRELOAD`
3763 * :setting:`SECURE_HSTS_SECONDS`
3764 * :setting:`SECURE_PROXY_SSL_HEADER`
3765 * :setting:`SECURE_REDIRECT_EXEMPT`
3766 * :setting:`SECURE_REFERRER_POLICY`
3767 * :setting:`SECURE_SSL_HOST`
3768 * :setting:`SECURE_SSL_REDIRECT`
3769 * :setting:`SIGNED_COOKIE_LEGACY_SALT_FALLBACK`
3770 * :setting:`SIGNING_BACKEND`
3771 * :setting:`USE_X_FORWARDED_HOST`
3772 * :setting:`USE_X_FORWARDED_PORT`
3773 * :setting:`WSGI_APPLICATION`
3774
3775 Logging
3776 -------
3777 * :setting:`LOGGING`
3778 * :setting:`LOGGING_CONFIG`
3779
3780 Models
3781 ------
3782 * :setting:`ABSOLUTE_URL_OVERRIDES`
3783 * :setting:`FIXTURE_DIRS`
3784 * :setting:`INSTALLED_APPS`
3785
3786 Security
3787 --------
3788 * Cross Site Request Forgery Protection
3789
3790 * :setting:`CSRF_COOKIE_DOMAIN`
3791 * :setting:`CSRF_COOKIE_NAME`
3792 * :setting:`CSRF_COOKIE_PATH`
3793 * :setting:`CSRF_COOKIE_SAMESITE`
3794 * :setting:`CSRF_COOKIE_SECURE`
3795 * :setting:`CSRF_FAILURE_VIEW`
3796 * :setting:`CSRF_HEADER_NAME`
3797 * :setting:`CSRF_TRUSTED_ORIGINS`
3798 * :setting:`CSRF_USE_SESSIONS`
3799
3800 * :setting:`SECRET_KEY`
3801 * :setting:`SECRET_KEY_FALLBACKS`
3802 * :setting:`X_FRAME_OPTIONS`
3803
3804 Serialization
3805 -------------
3806 * :setting:`DEFAULT_CHARSET`
3807 * :setting:`SERIALIZATION_MODULES`
3808
3809 Templates
3810 ---------
3811 * :setting:`TEMPLATES`
3812
3813 Testing
3814 -------
3815 * Database: :setting:`TEST <DATABASE-TEST>`
3816 * :setting:`TEST_NON_SERIALIZED_APPS`
3817 * :setting:`TEST_RUNNER`
3818
3819 URLs
3820 ----
3821 * :setting:`APPEND_SLASH`
3822 * :setting:`PREPEND_WWW`
3823 * :setting:`ROOT_URLCONF`