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

Add .env support to your django/flask apps in development and deployments

Project Description

_______ .__ __. ____ ____
| ____|| \ | | \ \ / /
| |__ | \| | \ \/ /
| __| | . ` | \ /
__ | |____ | |\ | \ /
(__)|_______||__| \__| \__/

python-dotenv | |Build Status| |Coverage Status| |PyPI version| |PyPI|

Reads the key,value pair from ``.env`` and adds them to environment
variable. It is great of managing app settings during development and in
production using `12-factor <>`__ principles.

Do one thing, do it well!

- `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 <#releated-projects>`__
- `Contributing <#contributing>`__
- `Changelog <#changelog>`__


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


├── .env

Add the following code to your ````

.. code:: python

from os.path import join, dirname
from dotenv import load_dotenv

dotenv_path = join(dirname(__file__), '.env')

# OR, the same with increased verbosity:
load_dotenv(dotenv_path, verbose=True)

Alternatively, 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.

.. code:: python

from dotenv import load_dotenv, find_dotenv

You can also set _load_dotenv_ to override existing variables:
.. code:: python

from dotenv import load_dotenv, find_dotenv
load_dotenv(find_dotenv(), override=True)

Now, you can access the variables either from system environment
variable or loaded from ``.env`` file. **System environment variables
gets higher precedence** and it's advised not to include it in version control.

.. code:: python


SECRET_KEY = os.environ.get("SECRET_KEY")

``.env`` is a simple text file. With each environment variables listed
per line, in the format of ``KEY="Value"``, lines starting with `#` is

.. code:: shell

# I am a comment and that is OK

``.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 <>`__.)

.. code:: shell



If you are using django you should add the above loader script at the
top of ```` and ````.



pip install -U python-dotenv

Command-line interface

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!


Usage: dotenv [OPTIONS] COMMAND [ARGS]...

This script is used to set, get or unset values from a .env file.

-f, --file PATH Location of the .env file, defaults to .env
file in current working directory.
-q, --quote [always|never|auto]
Whether to quote or not the variable values.
Default mode is always. This does not affect
--help Show this message and exit.

get Retrive the value for the given key.
list Display all the stored key/value.
set Store the given key/value.
unset Removes the given key.

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

# 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

Setting config on remote servers

We make use of excellent `Fabric <>`__ 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

.. code:: python


import dotenv
from fabric.api import task, run, env

# absolute path to the location of .env on remote server.
env.dotenv_path = '/opt/myapp/.env'

def config(action=None, key=None, value=None):
'''Manage project configuration via .env

e.g: fab config:set,<key>,<value>
fab config:get,<key>
fab config:unset,<key>
fab config:list
run('touch %(dotenv_path)s' % env)
command = dotenv.get_cli_string(env.dotenv_path, action, key, value)

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

Get all your remote config info with ``fab config``


$ fab config

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,<key1>,<value1> config:set,<key2>,<value2>``


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

Related Projects

- `Honcho <>`__ - For managing
Procfile-based applications.
- `django-dotenv <>`__
- `django-environ <>`__
- `django-configuration <>`__


All the contributions are welcome! Please open `an
issue <>`__ 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 <>`__.

Executing the tests:


$ flake8
$ pytest



- Remove hard dependency on iPython (`@theskumar`_)


- Add support to override system environment variable via .env. (`@milonimrod`_) (`#63`_)
- Disable ".env not found" warning by default (`@maxkoryukov`_) (`#57`_)

- Add support for special characters `\` (`@pjona`_) (`#60`_)

- Fix issue with single quotes (`@Flimm`_) (`#52`_)

- Handle unicode exception in (`#46`_)

- Fix `dotenv list` command (`@ticosax`_)
- Add iPython Suport (`@tillahoffmann`_)

- Drop support for Python 2.6
- Handle escaped charaters and newlines in quoted values. (Thanks `@iameugenejo`_)
- Remove any spaces around unquoted key/value. (Thanks `@paulochf`_)
- Added POSIX variable expansion. (Thanks `@hugochinchilla`_)

- Fix `find_dotenv` - it now start search from the file where this function is called from.

- Add ``find_dotenv`` method that will try to find a ``.env`` file. (Thanks `@isms`_)

- cli: Added ``-q/--quote`` option to control the behaviour of quotes around values in ``.env``. (Thanks `@hugochinchilla`_).
- Improved test coverage.

.. _@maxkoryukov:
.. _@maxkoryukov:
.. _@pjona:
.. _@Flimm:
.. _@ticosax:
.. _@tillahoffmann:
.. _@hugochinchilla:
.. _@isms:
.. _@iameugenejo:
.. _@paulochf:
.. _@paulochf:

.. _#63:
.. _#60:
.. _#57:
.. _#52:
.. _#46:

.. Saurabh Kumar:

.. |Build Status| image::
.. |Coverage Status| image::
.. |PyPI version| image::
.. |PyPI| image::
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


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
python_dotenv-0.7.1-py2.py3-none-any.whl (14.0 kB) Copy SHA256 Checksum SHA256 3.6 Wheel Sep 8, 2017
python-dotenv-0.7.1.tar.gz (10.6 kB) Copy SHA256 Checksum SHA256 Source Sep 8, 2017

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