Read key-value pairs from a .env file and set them as environment variables
Project description
python-dotenv
Python-dotenv reads key-value pairs from a .env
file and can set them as environment
variables. It helps in the development of applications following the
12-factor principles.
- Getting Started
- Other Use Cases
- Command-line Interface
- File format
- Related Projects
- Acknowledgements
Getting Started
pip install python-dotenv
If your application takes its configuration from environment variables, like a 12-factor application, launching it in development is not very practical because you have to set those environment variables yourself.
To help you with that, you can add Python-dotenv to your application to make it load the
configuration from a .env
file when it is present (e.g. in development) while remaining
configurable via the environment:
from dotenv import load_dotenv
load_dotenv() # take environment variables from .env.
# Code of your application, which uses environment variables (e.g. from `os.environ` or
# `os.getenv`) as if they came from the actual environment.
By default, load_dotenv
doesn't override existing environment variables.
To configure the development environment, add a .env
in the root directory of your
project:
.
├── .env
└── foo.py
The syntax of .env
files supported by python-dotenv is similar to that of Bash:
# Development settings
DOMAIN=example.org
ADMIN_EMAIL=admin@${DOMAIN}
ROOT_URL=${DOMAIN}/app
If you use variables in values, ensure they are surrounded with {
and }
, like
${DOMAIN}
, as bare variables such as $DOMAIN
are not expanded.
You will probably want to add .env
to your .gitignore
, especially if it contains
secrets like a password.
See the section "File format" below for more information about what you can write in a
.env
file.
Other Use Cases
Load configuration without altering the environment
The function dotenv_values
works more or less the same way as load_dotenv
, except it
doesn't touch the environment, it just returns a dict
with the values parsed from the
.env
file.
from dotenv import dotenv_values
config = dotenv_values(".env") # config = {"USER": "foo", "EMAIL": "foo@example.org"}
This notably enables advanced configuration management:
import os
from dotenv import dotenv_values
config = {
**dotenv_values(".env.shared"), # load shared development variables
**dotenv_values(".env.secret"), # load sensitive variables
**os.environ, # override loaded values with environment variables
}
Parse configuration as a stream
load_dotenv
and dotenv_values
accept streams via their stream
argument. It is thus possible to load the variables from sources other than the
filesystem (e.g. the network).
from io import StringIO
from dotenv import load_dotenv
config = StringIO("USER=foo\nEMAIL=foo@example.org")
load_dotenv(stream=config)
Load .env files in IPython
You can use dotenv in IPython. By default, it will use find_dotenv
to search for a
.env
file:
%load_ext dotenv
%dotenv
You can also specify a path:
%dotenv relative/or/absolute/path/to/.env
Optional flags:
-o
to override existing variables.-v
for increased verbosity.
Command-line Interface
A CLI interface dotenv
is also included, which helps you manipulate the .env
file
without manually opening it.
$ pip install "python-dotenv[cli]"
$ dotenv set USER foo
$ dotenv set EMAIL foo@example.org
$ dotenv list
USER=foo
EMAIL=foo@example.org
$ dotenv list --format=json
{
"USER": "foo",
"EMAIL": "foo@example.org"
}
$ dotenv run -- python foo.py
Run dotenv --help
for more information about the options and subcommands.
File format
The format is not formally specified and still improves over time. That being said,
.env
files should mostly look like Bash files.
Keys can be unquoted or single-quoted. Values can be unquoted, single- or double-quoted.
Spaces before and after keys, equal signs, and values are ignored. Values can be followed
by a comment. Lines can start with the export
directive, which has no effect on their
interpretation.
Allowed escape sequences:
- in single-quoted values:
\\
,\'
- in double-quoted values:
\\
,\'
,\"
,\a
,\b
,\f
,\n
,\r
,\t
,\v
Multiline values
It is possible for single- or double-quoted values to span multiple lines. The following examples are equivalent:
FOO="first line
second line"
FOO="first line\nsecond line"
Variable without a value
A variable can have no value:
FOO
It results in dotenv_values
associating that variable name with the value None
(e.g.
{"FOO": None}
. load_dotenv
, on the other hand, simply ignores such variables.
This shouldn't be confused with FOO=
, in which case the variable is associated with the
empty string.
Variable expansion
Python-dotenv can interpolate variables using POSIX variable expansion.
With load_dotenv(override=True)
or dotenv_values()
, the value of a variable is the
first of the values defined in the following list:
- Value of that variable in the
.env
file. - Value of that variable in the environment.
- Default value, if provided.
- Empty string.
With load_dotenv(override=False)
, the value of a variable is the first of the values
defined in the following list:
- Value of that variable in the environment.
- Value of that variable in the
.env
file. - Default value, if provided.
- Empty string.
Related Projects
- Honcho - For managing Procfile-based applications.
- django-dotenv
- django-environ
- django-environ-2
- django-configuration
- dump-env
- environs
- dynaconf
- parse_it
Acknowledgements
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.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
0.20.0 - 2022-03-24
Added
- Add
encoding
(Optional[str]
) parameter toget_key
,set_key
andunset_key
. (#379 by @bbc2)
Fixed
- Use dict to specify the
entry_points
parameter ofsetuptools.setup
(#376 by @mgorny). - Don't build universal wheels (#387 by @bbc2).
0.19.2 - 2021-11-11
Fixed
- In
set_key
, add missing newline character before new entry if necessary. (#361 by @bbc2)
0.19.1 - 2021-08-09
Added
- Add support for Python 3.10. (#359 by @theskumar)
0.19.0 - 2021-07-24
Changed
- Require Python 3.5 or a later version. Python 2 and 3.4 are no longer supported. (#341 by @bbc2).
Added
- The
dotenv_path
argument ofset_key
andunset_key
now has a type ofUnion[str, os.PathLike]
instead of justos.PathLike
(#347 by @bbc2). - The
stream
argument ofload_dotenv
anddotenv_values
can now be a text stream (IO[str]
), which includes values likeio.StringIO("foo")
andopen("file.env", "r")
(#348 by @bbc2).
0.18.0 - 2021-06-20
Changed
- Raise
ValueError
ifquote_mode
isn't one ofalways
,auto
ornever
inset_key
(#330 by @bbc2). - When writing a value to a .env file with
set_key
ordotenv set <key> <value>
(#330 by @bbc2):- Use single quotes instead of double quotes.
- Don't strip surrounding quotes.
- In
auto
mode, don't add quotes if the value is only made of alphanumeric characters (as determined bystring.isalnum
).
0.17.1 - 2021-04-29
Fixed
- Fixed tests for build environments relying on
PYTHONPATH
(#318 by @befeleme).
0.17.0 - 2021-04-02
Changed
- Make
dotenv get <key>
only show the value, notkey=value
(#313 by @bbc2).
Added
0.16.0 - 2021-03-27
Changed
- The default value of the
encoding
parameter forload_dotenv
anddotenv_values
is now"utf-8"
instead ofNone
(#306 by @bbc2). - Fix resolution order in variable expansion with
override=False
(#287 by @bbc2).
0.15.0 - 2020-10-28
Added
- Add
--export
option toset
to make it prepend the binding withexport
(#270 by @jadutter).
Changed
- Make
set
command create the.env
file in the current directory if no.env
file was found (#270 by @jadutter).
Fixed
- Fix potentially empty expanded value for duplicate key (#260 by @bbc2).
- Fix import error on Python 3.5.0 and 3.5.1 (#267 by @gongqingkui).
- Fix parsing of unquoted values containing several adjacent space or tab characters (#277 by @bbc2, review by @x-yuri).
0.14.0 - 2020-07-03
Changed
- Privilege definition in file over the environment in variable expansion (#256 by @elbehery95).
Fixed
- Improve error message for when file isn't found (#245 by @snobu).
- Use HTTPS URL in package meta data (#251 by @ekohl).
0.13.0 - 2020-04-16
Added
- Add support for a Bash-like default value in variable expansion (#248 by @bbc2).
0.12.0 - 2020-02-28
Changed
- Use current working directory to find
.env
when bundled by PyInstaller (#213 by @gergelyk).
Fixed
- Fix escaping of quoted values written by
set_key
(#236 by @bbc2). - Fix
dotenv run
crashing on environment variables without values (#237 by @yannham). - Remove warning when last line is empty (#238 by @bbc2).
0.11.0 - 2020-02-07
Added
- Add
interpolate
argument toload_dotenv
anddotenv_values
to disable interpolation (#232 by @ulyssessouza).
Changed
- Use logging instead of warnings (#231 by @bbc2).
Fixed
- Fix installation in non-UTF-8 environments (#225 by @altendky).
- Fix PyPI classifiers (#228 by @bbc2).
0.10.5 - 2020-01-19
Fixed
- Fix handling of malformed lines and lines without a value (#222 by @bbc2):
- Don't print warning when key has no value.
- Reject more malformed lines (e.g. "A: B", "a='b',c").
- Fix handling of lines with just a comment (#224 by @bbc2).
0.10.4 - 2020-01-17
Added
- Make typing optional (#179 by @techalchemy).
- Print a warning on malformed line (#211 by @bbc2).
- Support keys without a value (#220 by @ulyssessouza).
0.10.3
- Improve interactive mode detection (@andrewsmith)(#183).
- 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.
0.10.2
- 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)
0.10.1
0.10.0
- 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)
0.9.0
- Add
--version
parameter to cli (@venthur) - Enable loading from current directory (@cjauvin)
- Add 'dotenv run' command for calling arbitrary shell script with .env (@venthur)
0.8.1
- Add tests for docs (@Flimm)
- Make 'cli' support optional. Use
pip install python-dotenv[cli]
. (@theskumar)
0.8.0
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)
0.7.1
- Remove hard dependency on iPython (@theskumar)
0.7.0
- Add support to override system environment variable via .env. (@milonimrod) (#63)
- Disable ".env not found" warning by default (@maxkoryukov) (#57)
0.6.5
0.6.4
0.6.3
- Handle unicode exception in setup.py (#46)
0.6.2
- Fix dotenv list command (@ticosax)
- Add iPython Support (@tillahoffmann)
0.6.0
- Drop support for Python 2.6
- Handle escaped characters and newlines in quoted values. (Thanks @iameugenejo)
- Remove any spaces around unquoted key/value. (Thanks @paulochf)
- Added POSIX variable expansion. (Thanks @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)
0.4.0
- cli: Added
-q/--quote
option to control the behaviour of quotes around values in.env
. (Thanks @hugochinchilla). - Improved test coverage.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.