Django Stacked Settings

Simplify the obnoxious task of configuring the same Django project in multiple environments.


Django Stacked Settings allows you to place settings specific to different environments into separate files. Based on certain environmental conditions different settings can be loaded from multiple sources. This solves the classic issues of unnecessary development/production branches, or leaving uncommitted code changes sitting on a server.

The example use case is differentiating between development and production and individual machines, but the design is extremely flexible.

Unlike most other split-settings solutions, Django Stacked Settings maintains the global scope between settings files. Because of this, it's possible to modify settings initiated in a different file. This allows behavior like adding items to INSTALLED_APPS only in certain conditions.


Create the environment specific settings files

Start by creating a folder to store the settings files. Django Stacked Settings doesn't use import, so the folder doesn't need to be a package. You can call the folder anything you want, but "settings" is likely the most intuitive choice.

mkdir settings

Create a python script for each set of environmental conditions, containing the apropriate settings. For example, development.py might enable debugging and the Django Debug Toolbar.

Settings for development systems.

DEBUG = True




Note: Your source code editor may show warnings when modifying variables like INSTALLED_APPS because the scope is shared between all of the settings files. You can safely ignore these warnings as long as the variable is initialized in a file loaded before the current one. In this case, because MIDDLEWARE_CLASSES and INSTALLED_APPS are initialized in settings.py.

Additionally, you may want to create a settings file for each machine the application will run on.

Settings for the system identified as GLaDOS.

    'USER': 'dbuser',
    'PASSWORD': 'dbpassword',
    'NAME': 'example_testing_db_1'

MEDIA_ROOT = '/var/www/test/assets'
MEDIA_URL = '/assets/'
ADMIN_MEDIA_PREFIX = '/assets/admin/'


Install the module

PIP pip install django-stackedsettings or easy_install easy_install django-stackedsettings

Modify the project's settings.py

import os
import stackedsettings

PROJECT_PATH = os.path.abspath(os.path.dirname(__file__))

    ('glados': ('development', 'glados')),
    ('mainhost1', ('production', 'mainhost1)),


You can declare the STACKEDSETTINGS_* entries where you want in the settings.py file, but the line starting with stackedsettings.init should be at the end. All settings after this line will override those loaded with Django Stacked Settings.


Use these variables in settings.py to tailor Django Stacked Settings to your environment.


The possible values for STACKEDSETTINGS_METHOD are:

stackedsettings.HOSTNAME: Match against the server's hostname.

stackedsettings.FQDN: Match against the server's fully qualified domain name.

stackedsettings.ENV: Match against an environmental variable. See STACKEDSETTINGS_ENV_NAME.

stackedsettings.VAR: Match against a settings variable. See STACKEDSETTINGS_VAR_NAME.


This is the path to the directory where settings files are store. It defaults to "settings", but it's recommended that you provide a full path by setting and using "PROJECT_PATH".


A list of lists to determine which settings files to load. The first value in each list is a regular expression pattern to test. The second value is a list of modules (located within the settings directory) to load. If there is only one module, a string can be substituted for the list.

Note If multiple patterns match, only the first will be used.


The name of the environmental variable to use for ENV matching. Defaults to "STACKEDSETTINGS_KEY" if not set.


The name of the settings variable to use for VAR matching. Defaults to "PROJECT_PATH" if not set.