python-dotenv | [](https://travis-ci.org/theskumar/python-dotenv) [](https://coveralls.io/r/theskumar/python-dotenv?branch=master) [](http://badge.fury.io/py/python-dotenv) [](http://badge.fury.io/py/python-dotenv)

Reads the key,value pair from `.env` file and adds them to environment

variable. It is great for managing app settings during development and

in production using [12-factor](http://12factor.net/) principles.

- [Usages](#usages)

- [Installation](#installation)

- [Command-line interface](#command-line-interface)

- [iPython Support](#ipython-support)

- [Setting config on remote servers](#setting-config-on-remote-servers)

- [Related Projects](#related-projects)

- [Contributing](#contributing)

- [Changelog](#changelog)

Usages

The easiest and most common usage consists on calling `load_dotenv` when

the application starts, which will load environment variables from a

file named `.env` in the current directory or any of its parents or from

the path specificied; after that, you can just call the

environment-related method you need as provided by `os.getenv`.

`.env` looks like this:

REDIS_ADDRESS=localhost:6379

MEANING_OF_LIFE=42

MULTILINE_VAR="hello\nworld"

You can optionally prefix each line with the word `export`, which will

conveniently allow you to source the whole file on your shell.

`.env` can interpolate variables using POSIX variable expansion,

variables are replaced from the environment first or from other values

in the `.env` file if the variable is not present in the environment.

(`Note`: Default Value Expansion is not supported as of yet, see

[\#30](https://github.com/theskumar/python-dotenv/pull/30#issuecomment-244036604).)

CONFIG_PATH=${HOME}/.config/foo

DOMAIN=example.org

EMAIL=admin@${DOMAIN}

Getting started

Assuming you have created the `.env` file along-side your settings

module.

.

├── .env

└── settings.py

Add the following code to your `settings.py`

from dotenv import load_dotenv

load_dotenv()

load_dotenv(verbose=True)

from pathlib import Path # python3 only

env_path = Path('.') / '.env'

load_dotenv(dotenv_path=env_path)

At this point, parsed key/value from the .env file is now present as

system environment variable and they can be conveniently accessed via

import os

SECRET_KEY = os.getenv("EMAIL")

DATABASE_PASSWORD = os.getenv("DATABASE_PASSWORD")

`load_dotenv` do not override existing System environment variables. To

override, pass `override=True` to `load_dotenv()`.

You can use `find_dotenv()` method that will try to find a `.env` file

by (a) guessing where to start using `__file__` or the working directory

-- allowing this to work in non-file contexts such as IPython notebooks

and the REPL, and then (b) walking up the directory tree looking for the

specified file -- called `.env` by default.

from dotenv import load_dotenv, find_dotenv

load_dotenv(find_dotenv())

In-memory filelikes

It is possible to not rely on the filesystem to parse filelikes from

other sources (e.g. from a network storage). `load_dotenv` and

`dotenv_values` accepts a filelike `stream`. Just be sure to rewind it

before passing.

>>> from io import StringIO # Python2: from StringIO import StringIO

>>> from dotenv import dotenv_values

>>> filelike = StringIO('SPAM=EGSS\n')

>>> filelike.seek(0)

>>> parsed = dotenv_values(stream=filelike)

>>> parsed['SPAM']

The returned value is dictionary with key value pair.

`dotenv_values` could be useful if you need to *consume* the envfile but

not *apply* it directly into the system environment.

Django

If you are using django you should add the above loader script at the

top of `wsgi.py` and `manage.py`.

Installation

pip install -U python-dotenv

iPython Support

You can use dotenv with iPython. You can either let the dotenv search

for .env with %dotenv or provide the path to .env file explicitly, see

below for usages.

%load_ext dotenv

# Use find_dotenv to locate the file

%dotenv

# Specify a particular file

%dotenv relative/or/absolute/path/to/.env

# Use '-o' to indicate override of existing variables

%dotenv -o

# Use '-v' to turn verbose mode on

%dotenv -v

Command-line interface

For commandline support, use the cli option during installation:

pip install -U "python-dotenv[cli]"

A cli interface `dotenv` is also included, which helps you manipulate

the `.env` file without manually opening it. The same cli installed on

remote machine combined with fabric (discussed later) will enable you to

update your settings on remote server, handy isn't it!

Setting config on remote servers

We make use of excellent [Fabric](http://www.fabfile.org/) to acomplish

this. Add a config task to your local fabfile, `dotenv_path` is the

location of the absolute path of `.env` file on the remote server.

import dotenv

from fabric.api import task, run, env

env.dotenv_path = '/opt/myapp/.env'

def config(action=None, key=None, value=None):

'''Manage project configuration via .env

run('touch %(dotenv_path)s' % env)

command = dotenv.get_cli_string(env.dotenv_path, action, key, value)

run(command)

Usage is designed to mirror the heroku config api very closely.

Get all your remote config info with `fab config`

$ fab config

foo="bar"

Set remote config variables with `fab config:set,<key>,<value>`

$ fab config:set,hello,world

Get a single remote config variables with `fab config:get,<key>`

$ fab config:get,hello

Delete a remote config variables with `fab config:unset,<key>`

$ fab config:unset,hello

Thanks entirely to fabric and not one bit to this project, you can chain

commands like so

$ fab config:set,hello,world config:set,foo,bar config:set,fizz=buzz

Related Projects

- [Honcho](https://github.com/nickstenning/honcho) - For managing

Procfile-based applications.

- [django-dotenv](https://github.com/jpadilla/django-dotenv)

- [django-environ](https://github.com/joke2k/django-environ)

- [django-configuration](https://github.com/jezdez/django-configurations)

- [dump-env](https://github.com/sobolevn/dump-env)

Contributing

All the contributions are welcome! Please open [an

issue](https://github.com/theskumar/python-dotenv/issues/new) or send us

a pull request.

This project is currently maintained by Saurabh Kumar\_ and would not

have been possible without the support of these [awesome

people](https://github.com/theskumar/python-dotenv/graphs/contributors).

Executing the tests:

$ flake8

$ pytest

Changelog

0.8.1

- Add tests for docs ([@Flimm])

- Make 'cli' support optional. Use `pip install python-dotnev[cli]`. ([@theskumar])

0.8.0

- `set_key` and `unset_key` only modified the affected file instead of

parsing and re-writing file, this causes comments and other file

entact as it is.

- Add support for `export` prefix in the line.

- Internal refractoring ([@theskumar])

- Allow `load_dotenv` and `dotenv_values` to work with `StringIO())` ([@alanjds])([@theskumar])([#78])

0.7.1

- Remove hard dependency on iPython ([@theskumar])

0.7.0

- Add support to override system environment variable via .env.

([@milonimrod](https://github.com/milonimrod))

([\#63](https://github.com/theskumar/python-dotenv/issues/63))

- Disable ".env not found" warning by default

([@maxkoryukov](https://github.com/maxkoryukov))

([\#57](https://github.com/theskumar/python-dotenv/issues/57))

0.6.5

- Add support for special characters `\`.

([@pjona](https://github.com/pjona))

([\#60](https://github.com/theskumar/python-dotenv/issues/60))

0.6.4

- Fix issue with single quotes ([@Flimm])

([\#52](https://github.com/theskumar/python-dotenv/issues/52))

0.6.3

- Handle unicode exception in setup.py

([\#46](https://github.com/theskumar/python-dotenv/issues/46))

0.6.2

- Fix dotenv list command ([@ticosax](https://github.com/ticosax))

- Add iPython Suport

([@tillahoffmann](https://github.com/tillahoffmann))

0.6.0

- Drop support for Python 2.6

- Handle escaped charaters and newlines in quoted values. (Thanks

[@iameugenejo](https://github.com/iameugenejo))

- Remove any spaces around unquoted key/value. (Thanks

[@paulochf](https://github.com/paulochf))

- Added POSIX variable expansion. (Thanks

[@hugochinchilla](https://github.com/hugochinchilla))

0.5.1

- Fix find\_dotenv - it now start search from the file where this

function is called from.

0.5.0

- Add `find_dotenv` method that will try to find a `.env` file.

(Thanks [@isms](https://github.com/isms))

0.4.0

- cli: Added `-q/--quote` option to control the behaviour of quotes

around values in `.env`. (Thanks

[@hugochinchilla](https://github.com/hugochinchilla)).

- Improved test coverage.

[#78]: https://github.com/theskumar/python-dotenv/issues/78

[@Flimm]: https://github.com/Flimm

[@theskumar]: https://github.com/theskumar

[@alanjds]: https://github.com/alanjds