python-dotenv
Advanced tools
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.
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() # reads variables from a .env file and sets them in os.environ
# 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() will:
.env file in the same directory as the Python script (or higher up the directory tree).os.environ.override=True.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.
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
}
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)
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.Set PYTHON_DOTENV_DISABLED=1 to disable load_dotenv() from loading .env files or streams. Useful when you can't modify third-party package calls or in production.
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.
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 does not affect their
interpretation.
Allowed escape sequences:
\\, \'\\, \', \", \a, \b, \f, \n, \r, \t, \vIt 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"
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.
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:
.env file.With load_dotenv(override=False), the value of a variable is the first of the values
defined in the following list:
.env file.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.
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.
pyproject.toml, removed setup.cfg.env from FIFOs (Unix) by @sidharth-sudhir in #586build and pyproject.toml by @EpicWink in #583load_dotenv() using PYTHON_DOTENV_DISABLED env var. by @matthewfranglen in #569find_dotenv work reliably on python 3.13 by @theskumar in #563Feature
dotenv run, switch to execvpe for better resource management and signal handling (#523) by @eekstuntFixed
find_dotenv and load_dotenv now correctly looks up at the current directory when running in debugger or pdb (#553 by @randomseed42)Misc
Fixed
load_dotenv to be reloaded when launched in a separate thread ([#497] by @freddyaboulton)Misc
Fixed
Added
get and list commands when env file can't be opened (#441 by @bbc2)Fixed
magic (#440 by @bbc2)Added
load_dotenv function now returns False. (#388 by @larsks)Fixed
open instead of io.open. (#389 by @rabinadk1)parse_it to Related Projects (#410 by @naorlivne)Added
encoding (Optional[str]) parameter to get_key, set_key and unset_key.
(#379 by @bbc2)Fixed
entry_points parameter of setuptools.setup (#376 by
@mgorny).Fixed
set_key, add missing newline character before new entry if necessary. (#361 by
@bbc2)Added
Changed
Added
dotenv_path argument of set_key and unset_key now has a type of Union[str, os.PathLike] instead of just os.PathLike (#347 by @bbc2).stream argument of load_dotenv and dotenv_values can now be a text stream
(IO[str]), which includes values like io.StringIO("foo") and open("file.env", "r") (#348 by @bbc2).Changed
ValueError if quote_mode isn't one of always, auto or never in
set_key (#330 by @bbc2).set_key or dotenv set <key> <value> (#330
by @bbc2):
auto mode, don't add quotes if the value is only made of alphanumeric characters
(as determined by string.isalnum).Fixed
PYTHONPATH (#318 by @befeleme).Changed
dotenv get <key> only show the value, not key=value (#313 by @bbc2).Added
Changed
encoding parameter for load_dotenv and dotenv_values is
now "utf-8" instead of None (#306 by @bbc2).override=False (#287 by @bbc2).Added
--export option to set to make it prepend the binding with export (#270 by
@jadutter).Changed
set command create the .env file in the current directory if no .env file was
found (#270 by @jadutter).Fixed
Changed
Fixed
Added
Changed
.env when bundled by PyInstaller (#213 by
@gergelyk).Fixed
set_key (#236 by @bbc2).dotenv run crashing on environment variables without values (#237 by @yannham).Added
interpolate argument to load_dotenv and dotenv_values to disable interpolation
(#232 by @ulyssessouza).Changed
Fixed
Fixed
Added
# as start of comment only if preceded by whitespace.load_dotenv and dotenv_values now accept an encoding parameter, defaults to None
(@theskumar)(@earlbread)([#161])str/unicode inconsistency in Python 2: values are always str now. (@bbc2)(#121)--version parameter to cli (@venthur)pip install python-dotenv[cli]. (@theskumar)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.export prefix in the line.load_dotenv and dotenv_values to work with StringIO()) (@alanjds)(@theskumar)(#78)find_dotenv - it now start search from the file where this
function is called from.find_dotenv method that will try to find a .env file.
(Thanks @isms)-q/--quote option to control the behaviour of quotes
around values in .env. (Thanks
@hugochinchilla).FAQs
Read key-value pairs from a .env file and set them as environment variables
We found that python-dotenv demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh joins Software Engineering Daily to discuss modern software supply chain attacks and rising AI-driven security risks.
Security News
GitHub has revoked npm classic tokens for publishing; maintainers must migrate, but OpenJS warns OIDC trusted publishing still has risky gaps for critical projects.
Security News
Rust’s crates.io team is advancing an RFC to add a Security tab that surfaces RustSec vulnerability and unsoundness advisories directly on crate pages.