Welcome to django-environ-2 documentation

Release v2.3.0 (What's new?).

Disclaimer: This package is no longer maintained. Please use https://github.com/joke2k/django-environ instead.

django-environ-2 is the Python package that allows you to use Twelve-factor methodology to configure your Django application with environment variables.


The idea of this package is to unify a lot of packages that make the same stuff: Take a string from os.environ, parse and cast it to some of useful python typed variables. To do that and to use the 12factor approach, some connection strings are expressed as url, so this package can parse it and return a urllib.parse.ParseResult. These strings from os.environ are loaded from a .env file and filled in os.environ with setdefault method, to avoid to overwrite the real environ. A similar approach is used in Two Scoops of Django book and explained in 12factor-django article.

Using django-environ-2 you can stop to make a lot of unversioned settings_*.py to configure your app. See cookiecutter-django for a concrete example on using with a Django project.

Feature Support:

  • Fast and easy multi environment for deploy

  • Fill os.environ with .env file variables

  • Variables casting

  • Url variables exploded to Django specific package settings

Quick Start

import environ
import os

env = environ.Env(
    # set casting, default value
    DEBUG=(bool, False)

# Set the project base directory
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# Take environment variables from .env file
environ.Env.read_env(os.path.join(BASE_DIR, '.env'))

# False if not in os.environ because of casting above
DEBUG = env('DEBUG')

# Raises Django's ImproperlyConfigured
# exception if SECRET_KEY not in os.environ

# Parse database connection url strings
# like psql://user:pass@
    # read os.environ['DATABASE_URL'] and raises
    # ImproperlyConfigured exception if not found
    # The db() method is an alias for db_url().
    'default': env.db(),

    # read os.environ['SQLITE_URL']
    'extra': env.db_url(

    # Read os.environ['CACHE_URL'] and raises
    # ImproperlyConfigured exception if not found.
    # The cache() method is an alias for cache_url().
    'default': env.cache(),

    # read os.environ['REDIS_URL']
    'redis': env.cache_url('REDIS_URL')


Should you have any question, any remark, or if you find a bug, or if there is something you can’t do with the django-environ-2, please open an issue.

Similar projects

There are some projects similar to django-environ-2 you may be interested in:

Full Table of Contents

Project Information

django-environ-2 was forked from the django-environ initially written by Daniele Faraglia to breathe new life into it and set a more dynamic pace of development.

django-environ-2 is released under the MIT / X11 License, its documentation lives at Read the Docs, the code on GitHub, and the latest release on PyPI.

It’s rigorously tested on Python 3.6+, and officially supports Django 1.11, 2.2, 3.0, 3.1 and 3.2.

If you’d like to contribute to django-environ-2 you’re most welcome!

Indices and tables