This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

One-stop shop for configuring 12-factor Django apps

Project Description

One-stop shop for configuring 12-factor Django apps

  • Simple API for getting settings from environment variables.
  • Supports wide variety of email, cache and database backends.
  • Easily customisable and extensible.
  • One line auto-config for many Heroku add-ons.

Basic Settings

In your Django project’s

import envsettings

SECRET_KEY = envsettings.get('DJANGO_SECRET_KEY', 'development_key_not_a_secret')

# Accepts the strings "True" and "False"
DEBUG = envsettings.get_bool('DJANGO_DEBUG', default=True)

FILE_UPLOAD_MAX_MEMORY_SIZE = envsettings.get_int('MAX_UPLOAD_SIZE', default=2621440)

Email Settings

Because of the way Django’s email settings work, this requires a bit of a hack with locals():

import envsettings

locals().update('MAIL_URL', default='file:///dev/stdout'))

This sets EMAIL_BACKEND and whatever other values are needed to configure the selected backend.

Example URLs

Standard SMTP backend:

# SMTP without TLS
# SMTP with TLS

Special Django backends for use in development:

# Console backend

# Dummy packend

# File-based backend

Proprietary backends (each requires the appropriate package installed):

# Requires `django-mailgun`

# Requires `sendgrid-django`

# Requires `djrill`

# Requires `django-ses-backend`

# Requires `django-postmark`

Heroku Auto-Config

Pass auto_config=True like so:

locals().update('file:///dev/stdout', auto_config=True))

This will automatically detect and configure any of the following Heroku email add-ons: Mailgun, Sendgrid, Mandrill, Postmark.

So, for instance, you can configure your app to send email via Mailgun simply by running:

heroku addons:add mailgun:starter

By default it will use each provider’s SMTP endpoint, however if it detects that the appropriate backend is installed (see list above) it will configure Django to use the HTTP endpoint which will be faster.

Cache Settings

import envsettings

CACHES = {'default': envsettings.cache.get('CACHE_URL', 'locmem://')}

Example URLs

Django backends for use in development:

# Local memory
# Local memory with prefix

# File based

# Dummy cache

Redis (requires django-redis package):

# Basic Redis configuration
# With password
# Specifying database number
# Using UNIX socket
# Using UNIX socket with password and database number

To use Memcached you need one of the following packages installed: django_pylibmc, django_bmemcached, pylibmc, mecached

Only django_pylibmc and django_bmemcachd support authentication and the memcached binary protocol, so if you want to use either of these featues you’ll need one of those packages.

# Basic Memcached configuration
# Multiple servers
# With authentication
# Using the binary protocol

Heroku Auto-Config

Pass auto_config=True like so:

CACHES = {'default': envsettings.cache.get(default='locmen://', auto_config=True)}

This will automatically detect and configure any of the following Heroku cache add-ons: Memcachier, MemcachedCloud, RedisToGo, RedisCloud, OpenRedis, RedisGreen.

Customising & Extending

Django EnvSettings is designed to be easily extensible by subclassing one of the existing settings providers: CacheSettings, EmailSettings, or DatabaseSettings.

Changing default configuration

Obviously you can modify the configuration dictionary after it’s returned from envsettings. However you can also set default values for each backend, while letting the environment determine which backend to use. For example:

envsettings.database.CONFIG['postgres']['OPTIONS'] = {
    'isolation_level': psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE}

Supporting new backends

To add a new backend, subclass the appropriate settings class. You will then need to add a key to the CONFIG dictionary which maps the URL scheme you want to use for your backend to the default config for that backend. You will also need to add a method named handle_<URL_SCHEME>_url which will be passed the output from urlparse and the default config. The method should use the values from the parsed URL to update the config appropriately.

For example:

import envsettings

class CacheSettings(envsettings.CacheSettings):

    CONFIG = dict(envsettings.CacheSettings.CONFIG, **{
        'my-proto': {'BACKEND': 'my_cache_backend.MyCacheBackend'}

    def handle_my_proto_url(self, parsed_url, config):
        config['HOST'] = parsed_url.hostname or 'localhost'
        config['PORT'] = parsed_url.port or 9000
        config['USERNAME'] = parsed_url.username
        config['PASSWORD'] = parsed_url.password
        return config

cachesettings = CacheSettings()

CACHES = {'default': cachesettings.get('CACHE_URL')}

Supporting new auto configuration options

To add a new auto-configuration provider, subclass the appropriate settings class and add a method named auto_config_<PROVIDER_NAME>. This will be passed a dictionary of environment variables and should return either an appropriate configuration URL, or None.

The auto config methods are tried in lexical order, so if you want to force a method to be tried first you could call it auto_config_00_my_provider, or something like that.

Here’s an example:

import envsettings

class CacheSettings(envsettings.CacheSettings):

    def auto_config_my_redis(self, env):
            host = env['MY_REDIS_HOST']
            password = env['MY_REDIS_PASSWORD']
        except KeyError:
            return None
            return 'redis://:{password}@{host}'.format(
                host=host, password=password)

cachesettings = CacheSettings()

CACHES = {'default': cachesettings.get('CACHE_URL', auto_config=True)}


Tested on Python 2.7, 3.3, 3.4 and PyPy, with Django versions 1.41.7

Issues & Contributing

Raise an issue on the GitHub project or feel free to nudge @_EvansD on Twitter.


MIT Licensed

Release History

Release History

This version
History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
django_envsettings-1.1.0-py2.py3-none-any.whl (13.3 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Aug 20, 2015
django-envsettings-1.1.0.tar.gz (12.6 kB) Copy SHA256 Checksum SHA256 Source Aug 20, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting