_______ .__ __. ____ ____
| ____|| \ | | \ \ / /
| |__ | \| | \ \/ /
| __| | . ` | \ /
__ | |____ | |\ | \ /
(__)|_______||__| \__| \__/
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 principles.
Do one thing, do it well!
- Usages
- Installation
- Command-line interface
- iPython Support
- Setting config on remote servers
- Related Projects
- Contributing
- Changelog
Hey just wanted to let you know that since I've started writing 12-factor apps I've found python-dotenv to be invaluable for all my projects. It's super useful and “just works.” --Daniel Fridkin
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:
# a comment and that will be ignored.
REDIS_ADDRESS=localhost:6379
MEANING_OF_LIFE=42
MULTILINE_VAR="hello\nworld"
You can optionally prefix each line with the word export
, which is totally ignored by this library, but might allow you to source
the file in bash.
export S3_BUCKET=YOURS3BUCKET
export SECRET_KEY=YOURSECRETKEYGOESHERE
.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.)
CONFIG_PATH=${HOME}/.config/foo
DOMAIN=example.org
EMAIL=admin@${DOMAIN}
Assuming you have created the .env
file along-side your settings
module.
.
├── .env
└── settings.py
Add the following code to your settings.py
# settings.py
from dotenv import load_dotenv
load_dotenv()
# OR, the same with increased verbosity:
load_dotenv(verbose=True)
# OR, explicitly providing path to '.env'
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
os.getenv()
# settings.py
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()
.
load_dotenv
also accepts encoding
parameter to open the .env
file. The default encoding is platform dependent (whatever locale.getpreferredencoding()
returns), but any encoding supported by Python can be used. See the codecs module for the list of supported encodings.
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())
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=EGGS\n')
>>> filelike.seek(0)
>>> parsed = dotenv_values(stream=filelike)
>>> parsed['SPAM']
'EGGS'
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.
If you are using django you should add the above loader script at the
top of wsgi.py
and manage.py
.
pip install -U python-dotenv
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
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!
Usage: dotenv [OPTIONS] COMMAND [ARGS]...
This script is used to set, get or unset values from a .env file.
Options:
-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
parsing.
--help Show this message and exit.
Commands:
get Retrive the value for the given key.
list Display all the stored key/value.
run Run command with environment variables from .env file present
set Store the given key/value.
unset Removes the given key.
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 server.
# fabfile.py
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'
@task
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)
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,<key1>,<value1> config:set,<key2>,<value2>
$ fab config:set,hello,world config:set,foo,bar config:set,fizz=buzz
- Honcho - For managing Procfile-based applications.
- django-dotenv
- django-environ
- django-configuration
- dump-env
- environs
All the contributions are welcome! Please open an issue or send us a pull request.
This project is currently maintained by Saurabh Kumar and Bertrand Bonnefoy-Claudet and would not have been possible without the support of these awesome people.
Executing the tests:
$ pip install -r requirements.txt
$ pip install -e .
$ flake8
$ pytest
or with tox installed:
$ tox
- Refactor parser to fix parsing inconsistencies (@bbc2)(#170).
- Interpret escapes as control characters only in double-quoted strings.
- Interpret
#
as start of comment only if preceded by whitespace.
- Add type hints and expose them to users (@qnighy)(#172)
load_dotenv
anddotenv_values
now accept anencoding
parameter, defaults toNone
(@theskumar)(@earlbread)(#161)- Fix
str
/unicode
inconsistency in Python 2: values are alwaysstr
now. (@bbc2)(#121) - Fix Unicode error in Python 2, introduced in 0.10.0. (@bbc2)(#176)
- Add support for UTF-8 in unquoted values (@bbc2)(#148)
- Add support for trailing comments (@bbc2)(#148)
- Add backslashes support in values (@bbc2)(#148)
- Add support for newlines in values (@bbc2)(#148)
- Force environment variables to str with Python2 on Windows (@greyli)
- Drop Python 3.3 support (@greyli)
- Fix stderr/-out/-in redirection (@venthur)
- Add
--version
parameter to cli (@venthur) - Enable loading from current directory (@cjauvin)
- Add 'dotenv run' command for calling arbitrary shell script with .env (@venthur)
- Add tests for docs (@Flimm)
- Make 'cli' support optional. Use
pip install python-dotenv[cli]
. (@theskumar)
set_key
andunset_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
anddotenv_values
to work withStringIO())
(@alanjds)(@theskumar)(#78)
- 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)
- Handle unicode exception in setup.py (#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.