theskumar /python-dotenv
Reads key-value pairs from a .env file and can set them as environment variables. It helps in developing applications following the 12-factor principles.
★ 8,921⑂ 619👁 35⑃ 407● 340▤ 18
+0
Daily
8,921
stars
619
forks
35
watchers
407
prs
340
issues
18
releases
README
python-dotenv
[![Build Status][build_status_badge]][build_status_link]
[![PyPI version][pypi_badge]][pypi_link]
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
- Load configuration without altering the environment
- Parse configuration as a stream
- Load .env files in IPython
- Command-line Interface
- File format
- Multiline values
- Variable expansion
- Related Projects
- Acknowledgements
Getting Started
shell
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:
python
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:
- Look for a .env file in the same directory as the Python script (or higher up the directory tree).
- Read each key-value pair and add it to os.environ.
- Not override existing environment variables (override=False). Pass override=True to override existing 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:
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.
python
from dotenv import dotenv_values
config = dotenv_values(".env") config = {"USER": "foo", "EMAIL": "[email protected]"}
This notably enables advanced configuration management:
python
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
Top issues
#496Connection string in .env-file not read or parsed properly20 comments · 2024-01-12#418feature request: load multiple `.env` file before running a command9 comments · 2022-08-19#618Feature Request: generate a template from an env file8 comments · 2026-02-19#499AssertionError when attempting to locate dotenv file7 comments · 2024-01-23#683python-dotenv installation without cli masks python-dotenv cli5 comments · 2026-08-14#419ModuleNotFoundError: No module named '__main__' / load_dotenv() error on the latest Azure Functions (Python 3.9, Linux)5 comments · 2022-08-23#355dotenv_values returns an OrderedDict4 comments · 2021-08-31#354Feature Request: Generating .env.example file from a .env file4 comments · 2021-08-31
Latest release
v1.2.4 v1.2.4 2026-10-01Fixed
- dotenv get no longer exits with code 1 for empty string values (KEY=) by [@ShamikOfficial] in [700]
- An unquoted empty value followed by an inline comment (e.g. KEY= comment) is now parsed as an empty string instead of the comment text by [@Noethix55555] in [663]
- dotenv run --no-override now expands variable references with the same precedence as load_dotenv(override=False), so a value like ${BASE}/suffix uses the existing BASE from the environment instead of the one from the .env file by [@ROTl24] in [698]