1 ===============

     2 Django settings

     3 ===============

     4 

     5 A Django settings file contains all the configuration of your Django

     6 installation. This document explains how settings work and which settings are

     7 available.

     8 

     9 The basics

    10 ==========

    11 

    12 A settings file is just a Python module with module-level variables.

    13 

    14 Here are a couple of example settings::

    15 

    16     DEBUG = False

    17     DEFAULT_FROM_EMAIL = 'webmaster@example.com'

    18     TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')

    19 

    20 Because a settings file is a Python module, the following apply:

    21 

    22     * It doesn't allow for Python syntax errors.

    23     * It can assign settings dynamically using normal Python syntax.

    24       For example::

    25 

    26           MY_SETTING = [str(i) for i in range(30)]

    27 

    28     * It can import values from other settings files.

    29 

    30 .. _django-settings-module:

    31 

    32 Designating the settings

    33 ========================

    34 

    35 When you use Django, you have to tell it which settings you're using. Do this

    36 by using an environment variable, ``DJANGO_SETTINGS_MODULE``.

    37 

    38 The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g.

    39 ``mysite.settings``. Note that the settings module should be on the

    40 Python `import search path`_.

    41 

    42 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html

    43 

    44 The django-admin.py utility

    45 ---------------------------

    46 

    47 When using :doc:`django-admin.py </ref/django-admin>`, you can either set the

    48 environment variable once, or explicitly pass in the settings module each time

    49 you run the utility.

    50 

    51 Example (Unix Bash shell)::

    52 

    53     export DJANGO_SETTINGS_MODULE=mysite.settings

    54     django-admin.py runserver

    55 

    56 Example (Windows shell)::

    57 

    58     set DJANGO_SETTINGS_MODULE=mysite.settings

    59     django-admin.py runserver

    60 

    61 Use the ``--settings`` command-line argument to specify the settings manually::

    62 

    63     django-admin.py runserver --settings=mysite.settings

    64 

    65 .. _django-admin.py: ../django-admin/

    66 

    67 On the server (mod_python)

    68 --------------------------

    69 

    70 In your live server environment, you'll need to tell Apache/mod_python which

    71 settings file to use. Do that with ``SetEnv``::

    72 

    73     <Location "/mysite/">

    74         SetHandler python-program

    75         PythonHandler django.core.handlers.modpython

    76         SetEnv DJANGO_SETTINGS_MODULE mysite.settings

    77     </Location>

    78 

    79 Read the :doc:`Django mod_python documentation </howto/deployment/modpython>` for

    80 more information.

    81 

    82 Default settings

    83 ================

    84 

    85 A Django settings file doesn't have to define any settings if it doesn't need

    86 to. Each setting has a sensible default value. These defaults live in the

    87 module :file:`django/conf/global_settings.py`.

    88 

    89 Here's the algorithm Django uses in compiling settings:

    90 

    91     * Load settings from ``global_settings.py``.

    92     * Load settings from the specified settings file, overriding the global

    93       settings as necessary.

    94 

    95 Note that a settings file should *not* import from ``global_settings``, because

    96 that's redundant.

    97 

    98 Seeing which settings you've changed

    99 ------------------------------------

   100 

   101 There's an easy way to view which of your settings deviate from the default

   102 settings. The command ``python manage.py diffsettings`` displays differences

   103 between the current settings file and Django's default settings.

   104 

   105 For more, see the :djadmin:`diffsettings` documentation.

   106 

   107 Using settings in Python code

   108 =============================

   109 

   110 In your Django apps, use settings by importing the object

   111 ``django.conf.settings``. Example::

   112 

   113     from django.conf import settings

   114 

   115     if settings.DEBUG:

   116         # Do something

   117 

   118 Note that ``django.conf.settings`` isn't a module -- it's an object. So

   119 importing individual settings is not possible::

   120 

   121     from django.conf.settings import DEBUG  # This won't work.

   122 

   123 Also note that your code should *not* import from either ``global_settings`` or

   124 your own settings file. ``django.conf.settings`` abstracts the concepts of

   125 default settings and site-specific settings; it presents a single interface.

   126 It also decouples the code that uses settings from the location of your

   127 settings.

   128 

   129 Altering settings at runtime

   130 ============================

   131 

   132 You shouldn't alter settings in your applications at runtime. For example,

   133 don't do this in a view::

   134 

   135     from django.conf import settings

   136 

   137     settings.DEBUG = True   # Don't do this!

   138 

   139 The only place you should assign to settings is in a settings file.

   140 

   141 Security

   142 ========

   143 

   144 Because a settings file contains sensitive information, such as the database

   145 password, you should make every attempt to limit access to it. For example,

   146 change its file permissions so that only you and your Web server's user can

   147 read it. This is especially important in a shared-hosting environment.

   148 

   149 Available settings

   150 ==================

   151 

   152 For a full list of available settings, see the :doc:`settings reference </ref/settings>`.

   153 

   154 Creating your own settings

   155 ==========================

   156 

   157 There's nothing stopping you from creating your own settings, for your own

   158 Django apps. Just follow these conventions:

   159 

   160     * Setting names are in all uppercase.

   161     * Don't reinvent an already-existing setting.

   162 

   163 For settings that are sequences, Django itself uses tuples, rather than lists,

   164 but this is only a convention.

   165 

   166 .. _settings-without-django-settings-module:

   167 

   168 Using settings without setting DJANGO_SETTINGS_MODULE

   169 =====================================================

   170 

   171 In some cases, you might want to bypass the ``DJANGO_SETTINGS_MODULE``

   172 environment variable. For example, if you're using the template system by

   173 itself, you likely don't want to have to set up an environment variable

   174 pointing to a settings module.

   175 

   176 In these cases, you can configure Django's settings manually. Do this by

   177 calling:

   178 

   179 .. function:: django.conf.settings.configure(default_settings, **settings)

   180 

   181 Example::

   182 

   183     from django.conf import settings

   184 

   185     settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,

   186         TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))

   187 

   188 Pass ``configure()`` as many keyword arguments as you'd like, with each keyword

   189 argument representing a setting and its value. Each argument name should be all

   190 uppercase, with the same name as the settings described above. If a particular

   191 setting is not passed to ``configure()`` and is needed at some later point,

   192 Django will use the default setting value.

   193 

   194 Configuring Django in this fashion is mostly necessary -- and, indeed,

   195 recommended -- when you're using a piece of the framework inside a larger

   196 application.

   197 

   198 Consequently, when configured via ``settings.configure()``, Django will not

   199 make any modifications to the process environment variables (see the

   200 documentation of :setting:`TIME_ZONE` for why this would normally occur). It's

   201 assumed that you're already in full control of your environment in these

   202 cases.

   203 

   204 Custom default settings

   205 -----------------------

   206 

   207 If you'd like default values to come from somewhere other than

   208 ``django.conf.global_settings``, you can pass in a module or class that

   209 provides the default settings as the ``default_settings`` argument (or as the

   210 first positional argument) in the call to ``configure()``.

   211 

   212 In this example, default settings are taken from ``myapp_defaults``, and the

   213 ``DEBUG`` setting is set to ``True``, regardless of its value in

   214 ``myapp_defaults``::

   215 

   216     from django.conf import settings

   217     from myapp import myapp_defaults

   218 

   219     settings.configure(default_settings=myapp_defaults, DEBUG=True)

   220 

   221 The following example, which uses ``myapp_defaults`` as a positional argument,

   222 is equivalent::

   223 

   224     settings.configure(myapp_defaults, DEBUG = True)

   225 

   226 Normally, you will not need to override the defaults in this fashion. The

   227 Django defaults are sufficiently tame that you can safely use them. Be aware

   228 that if you do pass in a new default module, it entirely *replaces* the Django

   229 defaults, so you must specify a value for every possible setting that might be

   230 used in that code you are importing. Check in

   231 ``django.conf.settings.global_settings`` for the full list.

   232 

   233 Either configure() or DJANGO_SETTINGS_MODULE is required

   234 --------------------------------------------------------

   235 

   236 If you're not setting the ``DJANGO_SETTINGS_MODULE`` environment variable, you

   237 *must* call ``configure()`` at some point before using any code that reads

   238 settings.

   239 

   240 If you don't set ``DJANGO_SETTINGS_MODULE`` and don't call ``configure()``,

   241 Django will raise an ``ImportError`` exception the first time a setting

   242 is accessed.

   243 

   244 If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then*

   245 call ``configure()``, Django will raise a ``RuntimeError`` indicating

   246 that settings have already been configured.

   247 

   248 Also, it's an error to call ``configure()`` more than once, or to call

   249 ``configure()`` after any setting has been accessed.

   250 

   251 It boils down to this: Use exactly one of either ``configure()`` or

   252 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither.

   253 

   254 .. _@login_required: ../authentication/#the-login-required-decorator

   255