Getting Started

Installation

Requirements

Installing django-environ

django-environ is a Python-only package hosted on PyPI. The recommended installation method is pip-installing into a virtualenv:

$ python -m pip install django-environ

Note

After installing django-environ, no need to add it to INSTALLED_APPS.

Unstable version

The master of all the material is the Git repository at https://github.com/joke2k/django-environ. So, you can also install the latest unreleased development version directly from the develop branch on GitHub. It is a work-in-progress of a future stable release so the experience might be not as smooth.:

$ pip install -e git://github.com/joke2k/django-environ.git#egg=django-environ
# OR
$ pip install --upgrade https://github.com/joke2k/django-environ.git/archive/develop.tar.gz

This command will download the latest version of django-environ and install it to your system.

Note

The develop branch will always contain the latest unstable version, so the experience might be not as smooth. If you wish to check older versions or formal, tagged release, please switch to the relevant tag.

More information about pip and PyPI can be found here:

Usage

Create a .env file in project root directory. The file format can be understood from the example below:

DEBUG=on
SECRET_KEY=your-secret-key
DATABASE_URL=psql://user:un-githubbedpassword@127.0.0.1:8458/database
SQLITE_URL=sqlite:///my-local-sqlite.db
CACHE_URL=memcache://127.0.0.1:11211,127.0.0.1:11212,127.0.0.1:11213
REDIS_URL=rediscache://127.0.0.1:6379/1?client_class=django_redis.client.DefaultClient&password=ungithubbed-secret

And use it with settings.py as follows:

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
SECRET_KEY = env('SECRET_KEY')

# Parse database connection url strings
# like psql://user:pass@127.0.0.1:8458/db
DATABASES = {
    # 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(
        'SQLITE_URL',
        default='sqlite:////tmp/my-tmp-sqlite.db'
    )
}

CACHES = {
    # 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')
}

The .env file should be specific to the environment and not checked into version control, it is best practice documenting the .env file with an example. For example, you can also add .env.dist with a template of your variables to the project repo. This file should describe the mandatory variables for the Django application, and it can be committed to version control. This provides a useful reference and speeds up the on-boarding process for new team members, since the time to dig through the codebase to find out what has to be set up is reduced.

A good .env.dist could look like this:

# SECURITY WARNING: don't run with the debug turned on in production!
DEBUG=True

# Should robots.txt allow everything to be crawled?
ALLOW_ROBOTS=False

# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY=secret

# A list of all the people who get code error notifications.
ADMINS="John Doe <john@example.com>, Mary <mary@example.com>"

# A list of all the people who should get broken link notifications.
MANAGERS="Blake <blake@cyb.org>, Alice Judge <alice@cyb.org>"

# By default, Django will send system email from root@localhost.
# However, some mail providers reject all email from this address.
SERVER_EMAIL=webmaster@example.com

FAQ

  1. Can django-environ determine the location of .env file automatically?

    django-environ will try to get and read .env file from the project root if you haven’t specified the path for it when call read_env. However, this is not the recommended way. When it is possible always specify the path tho .env file. Alternatively, you can use a trick with a environment variable pointing to the actual location of .env file. For details see “Multiple env files”.

  2. What (where) is the root part of the project, is it part of the project where are settings?

    Where your manage.py file is (that is your project root directory).

  3. What kind of file should .env be?

    .env is a plain text file.

  4. Should name of the file be simply .env (or something.env)?

    Just .env. However, this is not a strict rule, but just a common practice. Formally, you can use any filename.

  5. Is .env file going to be imported in settings file?

    No need to import, django-environ automatically picks variables from there.