A Django settings file contains all the configuration of your Django\ninstallation. This document explains how settings work and which settings are\navailable.
\nA settings file is just a Python module with module-level variables.
\nHere are a couple of example settings:
\nALLOWED_HOSTS = ['www.example.com']\nDEBUG = False\nDEFAULT_FROM_EMAIL = 'webmaster@example.com'\nBecause a settings file is a Python module, the following apply:
\nIt doesn’t allow for Python syntax errors.
It can assign settings dynamically using normal Python syntax.\nFor example:
\nMY_SETTING = [str(i) for i in range(30)]\nIt can import values from other settings files.
When you use Django, you have to tell it which settings you’re using. Do this\nby using an environment variable, DJANGO_SETTINGS_MODULE.
The value of DJANGO_SETTINGS_MODULE should be in Python path syntax, e.g.\nmysite.settings. Note that the settings module should be on the\nPython import search path.
django-admin utilityLink to this heading#When using django-admin, you can either set the\nenvironment variable once, or explicitly pass in the settings module each time\nyou run the utility.
\nExample (Unix Bash shell):
\nexport DJANGO_SETTINGS_MODULE=mysite.settings\ndjango-admin runserver\nExample (Windows shell):
\nset DJANGO_SETTINGS_MODULE=mysite.settings\ndjango-admin runserver\nUse the --settings command-line argument to specify the settings manually:
django-admin runserver --settings=mysite.settings\nmod_wsgi)Link to this heading#In your live server environment, you’ll need to tell your WSGI\napplication what settings file to use. Do that with os.environ:
import os\n\nos.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'\nRead the Django mod_wsgi documentation for more information and other common\nelements to a Django WSGI application.
\nA Django settings file doesn’t have to define any settings if it doesn’t need\nto. Each setting has a sensible default value. These defaults live in the\nmodule django/conf/global_settings.py.
Here’s the algorithm Django uses in compiling settings:
\nLoad settings from global_settings.py.
Load settings from the specified settings file, overriding the global\nsettings as necessary.
Note that a settings file should not import from global_settings, because\nthat’s redundant.
There’s an easy way to view which of your settings deviate from the default\nsettings. The command python manage.py diffsettings displays differences\nbetween the current settings file and Django’s default settings.
For more, see the diffsettings documentation.
In your Django apps, use settings by importing the object\ndjango.conf.settings. Example:
from django.conf import settings\n\nif settings.DEBUG:\n # Do something\nNote that django.conf.settings isn’t a module – it’s an object. So\nimporting individual settings is not possible:
from django.conf.settings import DEBUG # This won't work.\nAlso note that your code should not import from either global_settings or\nyour own settings file. django.conf.settings abstracts the concepts of\ndefault settings and site-specific settings; it presents a single interface.\nIt also decouples the code that uses settings from the location of your\nsettings.
You shouldn’t alter settings in your applications at runtime. For example,\ndon’t do this in a view:
\nfrom django.conf import settings\n\nsettings.DEBUG = True # Don't do this!\nThe only place you should assign to settings is in a settings file.
\nBecause a settings file contains sensitive information, such as the database\npassword, you should make every attempt to limit access to it. For example,\nchange its file permissions so that only you and your Web server’s user can\nread it. This is especially important in a shared-hosting environment.
\nFor a full list of available settings, see the settings reference.
\nThere’s nothing stopping you from creating your own settings, for your own\nDjango apps. Just follow these guidelines:
\nSetting names must be all uppercase.
Don’t reinvent an already-existing setting.
For settings that are sequences, Django itself uses lists, but this is only\na convention.
\nDJANGO_SETTINGS_MODULELink to this heading#In some cases, you might want to bypass the DJANGO_SETTINGS_MODULE\nenvironment variable. For example, if you’re using the template system by\nitself, you likely don’t want to have to set up an environment variable\npointing to a settings module.
In these cases, you can configure Django’s settings manually. Do this by\ncalling:
\nExample:
\nfrom django.conf import settings\n\nsettings.configure(DEBUG=True)\nPass configure() as many keyword arguments as you’d like, with each keyword\nargument representing a setting and its value. Each argument name should be all\nuppercase, with the same name as the settings described above. If a particular\nsetting is not passed to configure() and is needed at some later point,\nDjango will use the default setting value.
Configuring Django in this fashion is mostly necessary – and, indeed,\nrecommended – when you’re using a piece of the framework inside a larger\napplication.
\nConsequently, when configured via settings.configure(), Django will not\nmake any modifications to the process environment variables (see the\ndocumentation of TIME_ZONE for why this would normally occur). It’s\nassumed that you’re already in full control of your environment in these\ncases.
If you’d like default values to come from somewhere other than\ndjango.conf.global_settings, you can pass in a module or class that\nprovides the default settings as the default_settings argument (or as the\nfirst positional argument) in the call to configure().
In this example, default settings are taken from myapp_defaults, and the\nDEBUG setting is set to True, regardless of its value in\nmyapp_defaults:
from django.conf import settings\nfrom myapp import myapp_defaults\n\nsettings.configure(default_settings=myapp_defaults, DEBUG=True)\nThe following example, which uses myapp_defaults as a positional argument,\nis equivalent:
settings.configure(myapp_defaults, DEBUG=True)\nNormally, you will not need to override the defaults in this fashion. The\nDjango defaults are sufficiently tame that you can safely use them. Be aware\nthat if you do pass in a new default module, it entirely replaces the Django\ndefaults, so you must specify a value for every possible setting that might be\nused in that code you are importing. Check in\ndjango.conf.settings.global_settings for the full list.
configure() or DJANGO_SETTINGS_MODULE is requiredLink to this heading#If you’re not setting the DJANGO_SETTINGS_MODULE environment variable, you\nmust call configure() at some point before using any code that reads\nsettings.
If you don’t set DJANGO_SETTINGS_MODULE and don’t call configure(),\nDjango will raise an ImportError exception the first time a setting\nis accessed.
If you set DJANGO_SETTINGS_MODULE, access settings values somehow, then\ncall configure(), Django will raise a RuntimeError indicating\nthat settings have already been configured. There is a property just for this\npurpose:
For example:
\nfrom django.conf import settings\nif not settings.configured:\n settings.configure(myapp_defaults, DEBUG=True)\nAlso, it’s an error to call configure() more than once, or to call\nconfigure() after any setting has been accessed.
It boils down to this: Use exactly one of either configure() or\nDJANGO_SETTINGS_MODULE. Not both, and not neither.
django.setup() is required for “standalone” Django usageLink to this heading#If you’re using components of Django “standalone” – for example, writing a\nPython script which loads some Django templates and renders them, or uses the\nORM to fetch some data – there’s one more step you’ll need in addition to\nconfiguring settings.
\nAfter you’ve either set DJANGO_SETTINGS_MODULE or called\nconfigure(), you’ll need to call django.setup() to load your\nsettings and populate Django’s application registry. For example:
import django\nfrom django.conf import settings\nfrom myapp import myapp_defaults\n\nsettings.configure(default_settings=myapp_defaults, DEBUG=True)\ndjango.setup()\n\n# Now this script or any imported module can use any part of Django it needs.\nfrom myapp import models\nNote that calling django.setup() is only necessary if your code is truly\nstandalone. When invoked by your Web server, or through django-admin, Django will handle this for you.