โน๏ธ Skipped - page is already crawled
| Filter | Status | Condition | Details |
|---|---|---|---|
| HTTP status | PASS | download_http_code = 200 | HTTP 200 |
| Age cutoff | PASS | download_stamp > now() - 6 MONTH | 0.1 months ago |
| History drop | PASS | isNull(history_drop_reason) | No drop reason |
| Spam/ban | PASS | fh_dont_index != 1 AND ml_spam_score = 0 | ml_spam_score=0 |
| Canonical | PASS | meta_canonical IS NULL OR = '' OR = src_unparsed | Not set |
| Property | Value |
|---|---|
| URL | https://pypi.org/project/python-dotenv/ |
| Last Crawled | 2026-04-05 10:18:21 (1 day ago) |
| First Indexed | 2017-05-12 03:43:52 (8 years ago) |
| HTTP Status Code | 200 |
| Meta Title | python-dotenv ยท PyPI |
| Meta Description | Read key-value pairs from a .env file and set them as environment variables |
| Meta Canonical | null |
| Boilerpipe Text | 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
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:
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:
# 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
\n
EMAIL=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.
Disable load_dotenv
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.
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. Reading from FIFOs (named
pipes) on Unix systems is also supported.
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:
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
environs
Honcho
dump-env
dynaconf
parse_it
django-dotenv
django-environ
python-decouple
django-configuration
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
.
[v1.2.2] - 2026-03-01
Added
Support for Python 3.14, including the free-threaded (3.14t) build. (#)
Changed
The
dotenv run
command now forwards flags directly to the specified command by
@bbc2
in
#607
Improved documentation clarity regarding override behavior and the reference page.
Updated PyPy support to version 3.11.
Documentation for FIFO file support.
Dropped Support for Python 3.9.
Fixed
Improved
set_key
and
unset_key
behavior when interacting with symlinks by
@bbc2
in
#790c5
Corrected the license specifier and added missing Python 3.14 classifiers in package metadata by
@JYOuyang
in
#590
Breaking Changes
dotenv.set_key
and
dotenv.unset_key
used to follow symlinks in some
situations. This is no longer the case. For that behavior to be restored in
all cases,
follow_symlinks=True
should be used.
In the CLI,
set
and
unset
used to follow symlinks in some situations. This
is no longer the case.
dotenv.set_key
,
dotenv.unset_key
and the CLI commands
set
and
unset
used to reset the file mode of the modified .env file to
0o600
in some
situations. This is no longer the case: The original mode of the file is now
preserved. Is the file needed to be created or wasn't a regular file, mode
0o600
is used.
1.2.1
- 2025-10-26
Move more config to
pyproject.toml
, removed
setup.cfg
Add support for reading
.env
from FIFOs (Unix) by
@sidharth-sudhir
in
#586
1.2.0
- 2025-10-26
Upgrade build system to use PEP 517 & PEP 518 to use
build
and
pyproject.toml
by
@EpicWink
in
#583
Add support for Python 3.14 by
@23f3001135
in
#579
Add support for disabling of
load_dotenv()
using
PYTHON_DOTENV_DISABLED
env var. by
@matthewfranglen
in
#569
1.1.1
- 2025-06-24
Fixed
CLI: Ensure
find_dotenv
work reliably on python 3.13 by
@theskumar
in
#563
CLI: revert the use of execvpe on Windows by
@wrongontheinternet
in
#566
1.1.0
- 2025-03-25
Feature
Add support for python 3.13
Enhance
dotenv run
, switch to
execvpe
for better resource management and signal handling (
#523
) by
@eekstunt
Fixed
find_dotenv
and
load_dotenv
now correctly looks up at the current directory when running in debugger or pdb (
#553
by
@randomseed42
)
Misc
Drop support for Python 3.8
1.0.1
- 2024-01-23
Fixed
Gracefully handle code which has been imported from a zipfile (
#456
by
@samwyma
)
Allow modules using
load_dotenv
to be reloaded when launched in a separate thread ([#497] by
@freddyaboulton
)
Fix file not closed after deletion, handle error in the rewrite function (
#469
by
@Qwerty-133
)
Misc
Use pathlib.Path in tests (
#466
by
@eumiro
)
Fix year in release date in changelog.md (
#454
by
@jankislinger
)
Use https in README links (
#474
by
@Nicals
)
1.0.0
- 2023-02-24
Fixed
Drop support for python 3.7, add python 3.12-dev (#449 by
@theskumar
)
Handle situations where the cwd does not exist. (#446 by
@jctanner
)
0.21.1
- 2023-01-21
Added
Use Python 3.11 non-beta in CI (#438 by
@bbc2
)
Modernize variables code (#434 by
@Nougat-Waffle
)
Modernize main.py and parser.py code (#435 by
@Nougat-Waffle
)
Improve conciseness of cli.py and
init
.py (#439 by
@Nougat-Waffle
)
Improve error message for
get
and
list
commands when env file can't be opened (#441 by
@bbc2
)
Updated License to align with BSD OSI template (#433 by
@lsmith77
)
Fixed
Fix Out-of-scope error when "dest" variable is undefined (#413 by
@theGOTOguy
)
Fix IPython test warning about deprecated
magic
(#440 by
@bbc2
)
Fix type hint for dotenv_path var, add StrPath alias (#432 by
@eaf
)
0.21.0
- 2022-09-03
Added
CLI: add support for invocations via 'python -m'. (#395 by
@theskumar
)
load_dotenv
function now returns
False
. (#388 by
@larsks
)
CLI: add --format= option to list command. (#407 by
@sammck
)
Fixed
Drop Python 3.5 and 3.6 and upgrade GA (#393 by
@eggplants
)
Use
open
instead of
io.open
. (#389 by
@rabinadk1
)
Improve documentation for variables without a value (#390 by
@bbc2
)
Add
parse_it
to Related Projects (#410 by
@naorlivne
)
Update README.md (#415 by
@harveer07
)
Improve documentation with direct use of MkDocs (#398 by
@bbc2
)
0.20.0
- 2022-03-24
Added
Add
encoding
(
Optional[str]
) parameter to
get_key
,
set_key
and
unset_key
.
(#379 by
@bbc2
)
Fixed
Use dict to specify the
entry_points
parameter of
setuptools.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 of
set_key
and
unset_key
now has a type of
Union[str, os.PathLike]
instead of just
os.PathLike
(#347 by
@bbc2
).
The
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
).
0.18.0
- 2021-06-20
Changed
Raise
ValueError
if
quote_mode
isn't one of
always
,
auto
or
never
in
set_key
(#330 by
@bbc2
).
When writing a value to a .env file with
set_key
or
dotenv 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 by
string.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, not
key=value
(#313 by
@bbc2
).
Added
Add
--override
/
--no-override
option to
dotenv run
(#312 by
@zueve
and
@bbc2
).
0.16.0
- 2021-03-27
Changed
The default value of the
encoding
parameter for
load_dotenv
and
dotenv_values
is
now
"utf-8"
instead of
None
(#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 to
set
to make it prepend the binding with
export
(#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 to
load_dotenv
and
dotenv_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
and
dotenv_values
now accept an
encoding
parameter, defaults to
None
(
@theskumar
)(
@earlbread
)([#161])
Fix
str
/
unicode
inconsistency in Python 2: values are always
str
now. (
@bbc2
)(
#121
)
Fix Unicode error in Python 2, introduced in 0.10.0. (
@bbc2
)(
#176
)
0.10.1
Fix parsing of variable without a value (
@asyncee
)(
@bbc2
)(
#158
)
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
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.
Add support for
export
prefix in the line.
Internal refractoring (
@theskumar
)
Allow
load_dotenv
and
dotenv_values
to work with
StringIO())
(
@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
Add support for special characters
\
.
(
@pjona
)
(
#60
)
0.6.4
Fix issue with single quotes (
@Flimm
)
(
#52
)
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. |
| Markdown | [Skip to main content](https://pypi.org/project/python-dotenv/#content)
Switch to mobile version
Warning Some features may not work without JavaScript. Please try enabling it if you encounter problems.
Join the official Python Developers Survey 2026 and have a chance to win a prize [Take the 2026 survey\!](https://surveys.jetbrains.com/s3/python-developers-survey-2026)
[](https://pypi.org/)
- [Help](https://pypi.org/help/)
- [Docs](https://docs.pypi.org/)
- [Sponsors](https://pypi.org/sponsors/)
- [Log in](https://pypi.org/account/login/?next=https%3A%2F%2Fpypi.org%2Fproject%2Fpython-dotenv%2F)
- [Register](https://pypi.org/account/register/)
Menu
- [Help](https://pypi.org/help/)
- [Docs](https://docs.pypi.org/)
- [Sponsors](https://pypi.org/sponsors/)
- [Log in](https://pypi.org/account/login/?next=https%3A%2F%2Fpypi.org%2Fproject%2Fpython-dotenv%2F)
- [Register](https://pypi.org/account/register/)
# python-dotenv 1.2.2
pip install python-dotenv Copy PIP instructions
[Latest version](https://pypi.org/project/python-dotenv/)
Released: Mar 1, 2026
Read key-value pairs from a .env file and set them as environment variables
### Navigation
- [Project description](https://pypi.org/project/python-dotenv/#description)
- [Release history](https://pypi.org/project/python-dotenv/#history)
- [Download files](https://pypi.org/project/python-dotenv/#files)
### Verified details
*These details have been [verified by PyPI](https://docs.pypi.org/project_metadata/#verified-details)*
###### Project links
- [Source](https://github.com/theskumar/python-dotenv)
###### GitHub Statistics
- [**Repository**](https://github.com/theskumar/python-dotenv)
- [**Stars:** 8696](https://github.com/theskumar/python-dotenv/stargazers)
- [**Forks:** 513](https://github.com/theskumar/python-dotenv/network/members)
- [**Open issues:** 52](https://github.com/theskumar/python-dotenv/issues)
- [**Open PRs:** 35](https://github.com/theskumar/python-dotenv/pulls)
###### Maintainers
[ bbc](https://pypi.org/user/bbc/) [ theskumar](https://pypi.org/user/theskumar/)
### Unverified details
*These details have **not** been verified by PyPI*
###### Meta
- **License:** BSD-3-Clause
- **Author:** [Saurabh Kumar](mailto:me+github@saurabh-kumar.com)
- Tags environment variables , deployments , settings , env , dotenv , configurations , python
- **Requires:** Python \>=3.10
- **Provides-Extra:** `cli`
###### Classifiers
- **Development Status**
- [5 - Production/Stable](https://pypi.org/search/?c=Development+Status+%3A%3A+5+-+Production%2FStable)
- **Environment**
- [Web Environment](https://pypi.org/search/?c=Environment+%3A%3A+Web+Environment)
- **Intended Audience**
- [Developers](https://pypi.org/search/?c=Intended+Audience+%3A%3A+Developers)
- [System Administrators](https://pypi.org/search/?c=Intended+Audience+%3A%3A+System+Administrators)
- **Operating System**
- [OS Independent](https://pypi.org/search/?c=Operating+System+%3A%3A+OS+Independent)
- **Programming Language**
- [Python](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python)
- [Python :: 3](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3)
- [Python :: 3.10](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.10)
- [Python :: 3.11](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.11)
- [Python :: 3.12](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.12)
- [Python :: 3.13](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.13)
- [Python :: 3.14](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.14)
- [Python :: Implementation :: PyPy](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+Implementation+%3A%3A+PyPy)
- **Topic**
- [System :: Systems Administration](https://pypi.org/search/?c=Topic+%3A%3A+System+%3A%3A+Systems+Administration)
- [Utilities](https://pypi.org/search/?c=Topic+%3A%3A+Utilities)
[Report project as malware](https://pypi.org/project/python-dotenv/submit-malware-report/)
- [Project description](https://pypi.org/project/python-dotenv/#description)
- [Project details](https://pypi.org/project/python-dotenv/#data)
- [Release history](https://pypi.org/project/python-dotenv/#history)
- [Download files](https://pypi.org/project/python-dotenv/#files)
## Project description
# python-dotenv
[](https://github.com/theskumar/python-dotenv/actions/workflows/test.yml) [](https://badge.fury.io/py/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](https://12factor.net/) principles.
- [Getting Started](https://pypi.org/project/python-dotenv/#getting-started)
- [Other Use Cases](https://pypi.org/project/python-dotenv/#other-use-cases)
- [Load configuration without altering the environment](https://pypi.org/project/python-dotenv/#load-configuration-without-altering-the-environment)
- [Parse configuration as a stream](https://pypi.org/project/python-dotenv/#parse-configuration-as-a-stream)
- [Load .env files in IPython](https://pypi.org/project/python-dotenv/#load-env-files-in-ipython)
- [Command-line Interface](https://pypi.org/project/python-dotenv/#command-line-interface)
- [File format](https://pypi.org/project/python-dotenv/#file-format)
- [Multiline values](https://pypi.org/project/python-dotenv/#multiline-values)
- [Variable expansion](https://pypi.org/project/python-dotenv/#variable-expansion)
- [Related Projects](https://pypi.org/project/python-dotenv/#related-projects)
- [Acknowledgements](https://pypi.org/project/python-dotenv/#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() # 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:
```
# 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](https://pypi.org/project/python-dotenv/#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](https://docs.python.org/3/library/io.html) 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.
### Disable load\_dotenv
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.
## 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. Reading from FIFOs (named pipes) on Unix systems is also supported.
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:
- 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
- [environs](https://github.com/sloria/environs)
- [Honcho](https://github.com/nickstenning/honcho)
- [dump-env](https://github.com/sobolevn/dump-env)
- [dynaconf](https://github.com/dynaconf/dynaconf)
- [parse\_it](https://github.com/naorlivne/parse_it)
- [django-dotenv](https://github.com/jpadilla/django-dotenv)
- [django-environ](https://github.com/joke2k/django-environ)
- [python-decouple](https://github.com/HBNetwork/python-decouple)
- [django-configuration](https://github.com/jezdez/django-configurations)
## Acknowledgements
This project is currently maintained by [Saurabh Kumar](https://saurabh-kumar.com/) and [Bertrand Bonnefoy-Claudet](https://github.com/bbc2) and would not have been possible without the support of these [awesome people](https://github.com/theskumar/python-dotenv/graphs/contributors).
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## \[v1.2.2\] - 2026-03-01
### Added
- Support for Python 3.14, including the free-threaded (3.14t) build. (\#)
### Changed
- The `dotenv run` command now forwards flags directly to the specified command by [@bbc2](https://github.com/bbc2) in [\#607](https://github.com/theskumar/python-dotenv/issues/607)
- Improved documentation clarity regarding override behavior and the reference page.
- Updated PyPy support to version 3.11.
- Documentation for FIFO file support.
- Dropped Support for Python 3.9.
### Fixed
- Improved `set_key` and `unset_key` behavior when interacting with symlinks by [@bbc2](https://github.com/bbc2) in [\#790c5](https://github.com/theskumar/python-dotenv/commit/790c5c02991100aa1bf41ee5330aca75edc51311)
- Corrected the license specifier and added missing Python 3.14 classifiers in package metadata by [@JYOuyang](https://github.com/JYOuyang) in [\#590](https://github.com/theskumar/python-dotenv/issues/590)
### Breaking Changes
- `dotenv.set_key` and `dotenv.unset_key` used to follow symlinks in some situations. This is no longer the case. For that behavior to be restored in all cases, `follow_symlinks=True` should be used.
- In the CLI, `set` and `unset` used to follow symlinks in some situations. This is no longer the case.
- `dotenv.set_key`, `dotenv.unset_key` and the CLI commands `set` and `unset` used to reset the file mode of the modified .env file to `0o600` in some situations. This is no longer the case: The original mode of the file is now preserved. Is the file needed to be created or wasn't a regular file, mode `0o600` is used.
## [1\.2.1](https://github.com/theskumar/python-dotenv/compare/v1.2.0...v1.2.1) - 2025-10-26
- Move more config to `pyproject.toml`, removed `setup.cfg`
- Add support for reading `.env` from FIFOs (Unix) by [@sidharth-sudhir](https://github.com/sidharth-sudhir) in [\#586](https://github.com/theskumar/python-dotenv/issues/586)
## [1\.2.0](https://github.com/theskumar/python-dotenv/compare/v1.1.1...v1.2.0) - 2025-10-26
- Upgrade build system to use PEP 517 & PEP 518 to use `build` and `pyproject.toml` by [@EpicWink](https://github.com/EpicWink) in [\#583](https://github.com/theskumar/python-dotenv/issues/583)
- Add support for Python 3.14 by [@23f3001135](https://github.com/23f3001135) in [\#579](https://github.com/theskumar/python-dotenv/pull/563)
- Add support for disabling of `load_dotenv()` using `PYTHON_DOTENV_DISABLED` env var. by [@matthewfranglen](https://github.com/matthewfranglen) in [\#569](https://github.com/theskumar/python-dotenv/issues/569)
## [1\.1.1](https://github.com/theskumar/python-dotenv/compare/v1.1.0...v1.1.1) - 2025-06-24
### Fixed
- CLI: Ensure `find_dotenv` work reliably on python 3.13 by [@theskumar](https://github.com/theskumar) in [\#563](https://github.com/theskumar/python-dotenv/pull/563)
- CLI: revert the use of execvpe on Windows by [@wrongontheinternet](https://github.com/wrongontheinternet) in [\#566](https://github.com/theskumar/python-dotenv/pull/566)
## [1\.1.0](https://github.com/theskumar/python-dotenv/compare/v1.0.1...v1.1.0) - 2025-03-25
**Feature**
- Add support for python 3.13
- Enhance `dotenv run`, switch to `execvpe` for better resource management and signal handling ([\#523](https://github.com/theskumar/python-dotenv/issues/523)) by [@eekstunt](https://github.com/eekstunt)
**Fixed**
- `find_dotenv` and `load_dotenv` now correctly looks up at the current directory when running in debugger or pdb ([\#553](https://github.com/theskumar/python-dotenv/issues/553) by [@randomseed42](https://github.com/zueve))
**Misc**
- Drop support for Python 3.8
## [1\.0.1](https://github.com/theskumar/python-dotenv/compare/v1.0.0...v1.0.1) - 2024-01-23
**Fixed**
- Gracefully handle code which has been imported from a zipfile ([\#456](https://github.com/theskumar/python-dotenv/issues/456) by [@samwyma](https://github.com/samwyma))
- Allow modules using `load_dotenv` to be reloaded when launched in a separate thread (\[\#497\] by [@freddyaboulton](https://github.com/freddyaboulton))
- Fix file not closed after deletion, handle error in the rewrite function ([\#469](https://github.com/theskumar/python-dotenv/issues/469) by [@Qwerty-133](https://github.com/Qwerty-133))
**Misc**
- Use pathlib.Path in tests ([\#466](https://github.com/theskumar/python-dotenv/issues/466) by [@eumiro](https://github.com/eumiro))
- Fix year in release date in changelog.md ([\#454](https://github.com/theskumar/python-dotenv/issues/454) by [@jankislinger](https://github.com/jankislinger))
- Use https in README links ([\#474](https://github.com/theskumar/python-dotenv/issues/474) by [@Nicals](https://github.com/Nicals))
## [1\.0.0](https://github.com/theskumar/python-dotenv/compare/v0.21.0...v1.0.0) - 2023-02-24
**Fixed**
- Drop support for python 3.7, add python 3.12-dev (\#449 by [@theskumar](https://github.com/theskumar))
- Handle situations where the cwd does not exist. (\#446 by [@jctanner](https://github.com/jctanner))
## [0\.21.1](https://github.com/theskumar/python-dotenv/compare/v0.21.0...v0.21.1) - 2023-01-21
**Added**
- Use Python 3.11 non-beta in CI (\#438 by [@bbc2](https://github.com/bbc2))
- Modernize variables code (\#434 by [@Nougat-Waffle](https://github.com/Nougat-Waffle))
- Modernize main.py and parser.py code (\#435 by [@Nougat-Waffle](https://github.com/Nougat-Waffle))
- Improve conciseness of cli.py and **init**.py (\#439 by [@Nougat-Waffle](https://github.com/Nougat-Waffle))
- Improve error message for `get` and `list` commands when env file can't be opened (\#441 by [@bbc2](https://github.com/bbc2))
- Updated License to align with BSD OSI template (\#433 by [@lsmith77](https://github.com/lsmith77))
**Fixed**
- Fix Out-of-scope error when "dest" variable is undefined (\#413 by [@theGOTOguy](https://github.com/theGOTOguy))
- Fix IPython test warning about deprecated `magic` (\#440 by [@bbc2](https://github.com/bbc2))
- Fix type hint for dotenv\_path var, add StrPath alias (\#432 by [@eaf](https://github.com/eaf))
## [0\.21.0](https://github.com/theskumar/python-dotenv/compare/v0.20.0...v0.21.0) - 2022-09-03
**Added**
- CLI: add support for invocations via 'python -m'. (\#395 by [@theskumar](https://github.com/theskumar))
- `load_dotenv` function now returns `False`. (\#388 by [@larsks](https://github.com/@larsks))
- CLI: add --format= option to list command. (\#407 by [@sammck](https://github.com/@sammck))
**Fixed**
- Drop Python 3.5 and 3.6 and upgrade GA (\#393 by [@eggplants](https://github.com/@eggplants))
- Use `open` instead of `io.open`. (\#389 by [@rabinadk1](https://github.com/@rabinadk1))
- Improve documentation for variables without a value (\#390 by [@bbc2](https://github.com/bbc2))
- Add `parse_it` to Related Projects (\#410 by [@naorlivne](https://github.com/@naorlivne))
- Update README.md (\#415 by [@harveer07](https://github.com/@harveer07))
- Improve documentation with direct use of MkDocs (\#398 by [@bbc2](https://github.com/bbc2))
## [0\.20.0](https://github.com/theskumar/python-dotenv/compare/v0.19.2...v0.20.0) - 2022-03-24
**Added**
- Add `encoding` (`Optional[str]`) parameter to `get_key`, `set_key` and `unset_key`. (\#379 by [@bbc2](https://github.com/bbc2))
**Fixed**
- Use dict to specify the `entry_points` parameter of `setuptools.setup` (\#376 by [@mgorny](https://github.com/mgorny)).
- Don't build universal wheels (\#387 by [@bbc2](https://github.com/bbc2)).
## [0\.19.2](https://github.com/theskumar/python-dotenv/compare/v0.19.1...v0.19.2) - 2021-11-11
**Fixed**
- In `set_key`, add missing newline character before new entry if necessary. (\#361 by [@bbc2](https://github.com/bbc2))
## [0\.19.1](https://github.com/theskumar/python-dotenv/compare/v0.19.0...v0.19.1) - 2021-08-09
**Added**
- Add support for Python 3.10. (\#359 by [@theskumar](https://github.com/theskumar))
## [0\.19.0](https://github.com/theskumar/python-dotenv/compare/v0.18.0...v0.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](https://github.com/bbc2)).
**Added**
- The `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](https://github.com/bbc2)).
- The `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](https://github.com/bbc2)).
## [0\.18.0](https://github.com/theskumar/python-dotenv/compare/v0.17.1...v0.18.0) - 2021-06-20
**Changed**
- Raise `ValueError` if `quote_mode` isn't one of `always`, `auto` or `never` in `set_key` (\#330 by [@bbc2](https://github.com/bbc2)).
- When writing a value to a .env file with `set_key` or `dotenv set <key> <value>` (\#330 by [@bbc2](https://github.com/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 by `string.isalnum`).
## [0\.17.1](https://github.com/theskumar/python-dotenv/compare/v0.17.0...v0.17.1) - 2021-04-29
**Fixed**
- Fixed tests for build environments relying on `PYTHONPATH` (\#318 by [@befeleme](https://github.com/befeleme)).
## [0\.17.0](https://github.com/theskumar/python-dotenv/compare/v0.16.0...v0.17.0) - 2021-04-02
**Changed**
- Make `dotenv get <key>` only show the value, not `key=value` (\#313 by [@bbc2](https://github.com/bbc2)).
**Added**
- Add `--override`/`--no-override` option to `dotenv run` (\#312 by [@zueve](https://github.com/zueve) and [@bbc2](https://github.com/bbc2)).
## [0\.16.0](https://github.com/theskumar/python-dotenv/compare/v0.15.0...v0.16.0) - 2021-03-27
**Changed**
- The default value of the `encoding` parameter for `load_dotenv` and `dotenv_values` is now `"utf-8"` instead of `None` (\#306 by [@bbc2](https://github.com/bbc2)).
- Fix resolution order in variable expansion with `override=False` (\#287 by [@bbc2](https://github.com/bbc2)).
## [0\.15.0](https://github.com/theskumar/python-dotenv/compare/v0.14.0...v0.15.0) - 2020-10-28
**Added**
- Add `--export` option to `set` to make it prepend the binding with `export` (\#270 by [@jadutter](https://github.com/jadutter)).
**Changed**
- Make `set` command create the `.env` file in the current directory if no `.env` file was found (\#270 by [@jadutter](https://github.com/jadutter)).
**Fixed**
- Fix potentially empty expanded value for duplicate key (\#260 by [@bbc2](https://github.com/bbc2)).
- Fix import error on Python 3.5.0 and 3.5.1 (\#267 by [@gongqingkui](https://github.com/gongqingkui)).
- Fix parsing of unquoted values containing several adjacent space or tab characters (\#277 by [@bbc2](https://github.com/bbc2), review by [@x-yuri](https://github.com/x-yuri)).
## [0\.14.0](https://github.com/theskumar/python-dotenv/compare/v0.13.0...v0.14.0) - 2020-07-03
**Changed**
- Privilege definition in file over the environment in variable expansion (\#256 by [@elbehery95](https://github.com/elbehery95)).
**Fixed**
- Improve error message for when file isn't found (\#245 by [@snobu](https://github.com/snobu)).
- Use HTTPS URL in package meta data (\#251 by [@ekohl](https://github.com/ekohl)).
## [0\.13.0](https://github.com/theskumar/python-dotenv/compare/v0.12.0...v0.13.0) - 2020-04-16
**Added**
- Add support for a Bash-like default value in variable expansion (\#248 by [@bbc2](https://github.com/bbc2)).
## [0\.12.0](https://github.com/theskumar/python-dotenv/compare/v0.11.0...v0.12.0) - 2020-02-28
**Changed**
- Use current working directory to find `.env` when bundled by PyInstaller (\#213 by [@gergelyk](https://github.com/gergelyk)).
**Fixed**
- Fix escaping of quoted values written by `set_key` (\#236 by [@bbc2](https://github.com/bbc2)).
- Fix `dotenv run` crashing on environment variables without values (\#237 by [@yannham](https://github.com/yannham)).
- Remove warning when last line is empty (\#238 by [@bbc2](https://github.com/bbc2)).
## [0\.11.0](https://github.com/theskumar/python-dotenv/compare/v0.10.5...v0.11.0) - 2020-02-07
**Added**
- Add `interpolate` argument to `load_dotenv` and `dotenv_values` to disable interpolation (\#232 by [@ulyssessouza](https://github.com/ulyssessouza)).
**Changed**
- Use logging instead of warnings (\#231 by [@bbc2](https://github.com/bbc2)).
**Fixed**
- Fix installation in non-UTF-8 environments (\#225 by [@altendky](https://github.com/altendky)).
- Fix PyPI classifiers (\#228 by [@bbc2](https://github.com/bbc2)).
## [0\.10.5](https://github.com/theskumar/python-dotenv/compare/v0.10.4...v0.10.5) - 2020-01-19
**Fixed**
- Fix handling of malformed lines and lines without a value (\#222 by [@bbc2](https://github.com/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](https://github.com/bbc2)).
## [0\.10.4](https://github.com/theskumar/python-dotenv/compare/v0.10.3...v0.10.4) - 2020-01-17
**Added**
- Make typing optional (\#179 by [@techalchemy](https://github.com/techalchemy)).
- Print a warning on malformed line (\#211 by [@bbc2](https://github.com/bbc2)).
- Support keys without a value (\#220 by [@ulyssessouza](https://github.com/ulyssessouza)).
## 0\.10.3
- Improve interactive mode detection ([@andrewsmith](https://github.com/andrewsmith))([\#183](https://github.com/theskumar/python-dotenv/issues/183)).
- Refactor parser to fix parsing inconsistencies ([@bbc2](https://github.com/bbc2))([\#170](https://github.com/theskumar/python-dotenv/issues/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](https://github.com/qnighy))([\#172](https://github.com/theskumar/python-dotenv/issues/172))
- `load_dotenv` and `dotenv_values` now accept an `encoding` parameter, defaults to `None` ([@theskumar](https://github.com/theskumar))([@earlbread](https://github.com/earlbread))(\[\#161\])
- Fix `str`/`unicode` inconsistency in Python 2: values are always `str` now. ([@bbc2](https://github.com/bbc2))([\#121](https://github.com/theskumar/python-dotenv/issues/121))
- Fix Unicode error in Python 2, introduced in 0.10.0. ([@bbc2](https://github.com/bbc2))([\#176](https://github.com/theskumar/python-dotenv/issues/176))
## 0\.10.1
- Fix parsing of variable without a value ([@asyncee](https://github.com/asyncee))([@bbc2](https://github.com/bbc2))([\#158](https://github.com/theskumar/python-dotenv/issues/158))
## 0\.10.0
- Add support for UTF-8 in unquoted values ([@bbc2](https://github.com/bbc2))([\#148](https://github.com/theskumar/python-dotenv/issues/148))
- Add support for trailing comments ([@bbc2](https://github.com/bbc2))([\#148](https://github.com/theskumar/python-dotenv/issues/148))
- Add backslashes support in values ([@bbc2](https://github.com/bbc2))([\#148](https://github.com/theskumar/python-dotenv/issues/148))
- Add support for newlines in values ([@bbc2](https://github.com/bbc2))([\#148](https://github.com/theskumar/python-dotenv/issues/148))
- Force environment variables to str with Python2 on Windows ([@greyli](https://github.com/greyli))
- Drop Python 3.3 support ([@greyli](https://github.com/greyli))
- Fix stderr/-out/-in redirection ([@venthur](https://github.com/venthur))
## 0\.9.0
- Add `--version` parameter to cli ([@venthur](https://github.com/venthur))
- Enable loading from current directory ([@cjauvin](https://github.com/cjauvin))
- Add 'dotenv run' command for calling arbitrary shell script with .env ([@venthur](https://github.com/venthur))
## 0\.8.1
- Add tests for docs ([@Flimm](https://github.com/Flimm))
- Make 'cli' support optional. Use `pip install python-dotenv[cli]`. ([@theskumar](https://github.com/theskumar))
## 0\.8.0
- `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.
- Add support for `export` prefix in the line.
- Internal refractoring ([@theskumar](https://github.com/theskumar))
- Allow `load_dotenv` and `dotenv_values` to work with `StringIO())` ([@alanjds](https://github.com/alanjds))([@theskumar](https://github.com/theskumar))([\#78](https://github.com/theskumar/python-dotenv/issues/78))
## 0\.7.1
- Remove hard dependency on iPython ([@theskumar](https://github.com/theskumar))
## 0\.7.0
- Add support to override system environment variable via .env. ([@milonimrod](https://github.com/milonimrod)) ([\#63](https://github.com/theskumar/python-dotenv/issues/63))
- Disable ".env not found" warning by default ([@maxkoryukov](https://github.com/maxkoryukov)) ([\#57](https://github.com/theskumar/python-dotenv/issues/57))
## 0\.6.5
- Add support for special characters `\`. ([@pjona](https://github.com/pjona)) ([\#60](https://github.com/theskumar/python-dotenv/issues/60))
## 0\.6.4
- Fix issue with single quotes ([@Flimm](https://github.com/Flimm)) ([\#52](https://github.com/theskumar/python-dotenv/issues/52))
## 0\.6.3
- Handle unicode exception in setup.py ([\#46](https://github.com/theskumar/python-dotenv/issues/46))
## 0\.6.2
- Fix dotenv list command ([@ticosax](https://github.com/ticosax))
- Add iPython Support ([@tillahoffmann](https://github.com/tillahoffmann))
## 0\.6.0
- Drop support for Python 2.6
- Handle escaped characters and newlines in quoted values. (Thanks [@iameugenejo](https://github.com/iameugenejo))
- Remove any spaces around unquoted key/value. (Thanks [@paulochf](https://github.com/paulochf))
- Added POSIX variable expansion. (Thanks [@hugochinchilla](https://github.com/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](https://github.com/isms))
## 0\.4.0
- cli: Added `-q/--quote` option to control the behaviour of quotes around values in `.env`. (Thanks [@hugochinchilla](https://github.com/hugochinchilla)).
- Improved test coverage.
## Project details
### Verified details
*These details have been [verified by PyPI](https://docs.pypi.org/project_metadata/#verified-details)*
###### Project links
- [Source](https://github.com/theskumar/python-dotenv)
###### GitHub Statistics
- [**Repository**](https://github.com/theskumar/python-dotenv)
- [**Stars:** 8696](https://github.com/theskumar/python-dotenv/stargazers)
- [**Forks:** 513](https://github.com/theskumar/python-dotenv/network/members)
- [**Open issues:** 52](https://github.com/theskumar/python-dotenv/issues)
- [**Open PRs:** 35](https://github.com/theskumar/python-dotenv/pulls)
###### Maintainers
[ bbc](https://pypi.org/user/bbc/) [ theskumar](https://pypi.org/user/theskumar/)
### Unverified details
*These details have **not** been verified by PyPI*
###### Meta
- **License:** BSD-3-Clause
- **Author:** [Saurabh Kumar](mailto:me+github@saurabh-kumar.com)
- Tags environment variables , deployments , settings , env , dotenv , configurations , python
- **Requires:** Python \>=3.10
- **Provides-Extra:** `cli`
###### Classifiers
- **Development Status**
- [5 - Production/Stable](https://pypi.org/search/?c=Development+Status+%3A%3A+5+-+Production%2FStable)
- **Environment**
- [Web Environment](https://pypi.org/search/?c=Environment+%3A%3A+Web+Environment)
- **Intended Audience**
- [Developers](https://pypi.org/search/?c=Intended+Audience+%3A%3A+Developers)
- [System Administrators](https://pypi.org/search/?c=Intended+Audience+%3A%3A+System+Administrators)
- **Operating System**
- [OS Independent](https://pypi.org/search/?c=Operating+System+%3A%3A+OS+Independent)
- **Programming Language**
- [Python](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python)
- [Python :: 3](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3)
- [Python :: 3.10](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.10)
- [Python :: 3.11](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.11)
- [Python :: 3.12](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.12)
- [Python :: 3.13](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.13)
- [Python :: 3.14](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+3.14)
- [Python :: Implementation :: PyPy](https://pypi.org/search/?c=Programming+Language+%3A%3A+Python+%3A%3A+Implementation+%3A%3A+PyPy)
- **Topic**
- [System :: Systems Administration](https://pypi.org/search/?c=Topic+%3A%3A+System+%3A%3A+Systems+Administration)
- [Utilities](https://pypi.org/search/?c=Topic+%3A%3A+Utilities)
## Release history [Release notifications](https://pypi.org/help/#project-release-notifications) \| [RSS feed](https://pypi.org/rss/project/python-dotenv/releases.xml)
This version
[1\.2.2 Mar 1, 2026](https://pypi.org/project/python-dotenv/1.2.2/)
[1\.2.1 Oct 26, 2025](https://pypi.org/project/python-dotenv/1.2.1/)
[1\.2.0 Oct 26, 2025](https://pypi.org/project/python-dotenv/1.2.0/)
[1\.1.1 Jun 24, 2025](https://pypi.org/project/python-dotenv/1.1.1/)
[1\.1.0 Mar 25, 2025](https://pypi.org/project/python-dotenv/1.1.0/)
[1\.0.1 Jan 23, 2024](https://pypi.org/project/python-dotenv/1.0.1/)
[1\.0.0 Feb 24, 2023](https://pypi.org/project/python-dotenv/1.0.0/)
[0\.21.1 Jan 21, 2023](https://pypi.org/project/python-dotenv/0.21.1/)
[0\.21.0 Sep 3, 2022](https://pypi.org/project/python-dotenv/0.21.0/)
[0\.20.0 Mar 24, 2022](https://pypi.org/project/python-dotenv/0.20.0/)
[0\.19.2 Nov 11, 2021](https://pypi.org/project/python-dotenv/0.19.2/)
[0\.19.1 Oct 9, 2021](https://pypi.org/project/python-dotenv/0.19.1/)
[0\.19.0 Jul 24, 2021](https://pypi.org/project/python-dotenv/0.19.0/)
[0\.18.0 Jun 20, 2021](https://pypi.org/project/python-dotenv/0.18.0/)
[0\.17.1 Apr 29, 2021](https://pypi.org/project/python-dotenv/0.17.1/)
[0\.17.0 Apr 2, 2021](https://pypi.org/project/python-dotenv/0.17.0/)
[0\.16.0 Mar 27, 2021](https://pypi.org/project/python-dotenv/0.16.0/)
[0\.15.0 Oct 28, 2020](https://pypi.org/project/python-dotenv/0.15.0/)
[0\.14.0 Jul 3, 2020](https://pypi.org/project/python-dotenv/0.14.0/)
[0\.13.0 Apr 16, 2020](https://pypi.org/project/python-dotenv/0.13.0/)
[0\.12.0 Feb 28, 2020](https://pypi.org/project/python-dotenv/0.12.0/)
[0\.11.0 Feb 7, 2020](https://pypi.org/project/python-dotenv/0.11.0/)
[0\.10.5 Jan 19, 2020](https://pypi.org/project/python-dotenv/0.10.5/)
[0\.10.4 Jan 17, 2020](https://pypi.org/project/python-dotenv/0.10.4/)
[0\.10.3 Jun 2, 2019](https://pypi.org/project/python-dotenv/0.10.3/)
[0\.10.2 May 12, 2019](https://pypi.org/project/python-dotenv/0.10.2/)
[0\.10.1 Dec 14, 2018](https://pypi.org/project/python-dotenv/0.10.1/)
[0\.10.0 Dec 5, 2018](https://pypi.org/project/python-dotenv/0.10.0/)
[0\.9.1 Aug 5, 2018](https://pypi.org/project/python-dotenv/0.9.1/)
[0\.9.0 Jul 31, 2018](https://pypi.org/project/python-dotenv/0.9.0/)
[0\.8.2 Mar 7, 2018](https://pypi.org/project/python-dotenv/0.8.2/)
[0\.8.1 Mar 7, 2018](https://pypi.org/project/python-dotenv/0.8.1/)
[0\.8.0 Mar 3, 2018](https://pypi.org/project/python-dotenv/0.8.0/)
[0\.7.1 Sep 8, 2017](https://pypi.org/project/python-dotenv/0.7.1/)
[0\.7.0 Sep 8, 2017](https://pypi.org/project/python-dotenv/0.7.0/)
[0\.6.5 Aug 9, 2017](https://pypi.org/project/python-dotenv/0.6.5/)
[0\.6.4 Mar 30, 2017](https://pypi.org/project/python-dotenv/0.6.4/)
[0\.6.3 Feb 3, 2017](https://pypi.org/project/python-dotenv/0.6.3/)
[0\.6.2 Jan 12, 2017](https://pypi.org/project/python-dotenv/0.6.2/)
[0\.6.1 Nov 10, 2016](https://pypi.org/project/python-dotenv/0.6.1/)
[0\.6.0 Sep 8, 2016](https://pypi.org/project/python-dotenv/0.6.0/)
[0\.5.1 May 28, 2016](https://pypi.org/project/python-dotenv/0.5.1/)
[0\.5.0 May 1, 2016](https://pypi.org/project/python-dotenv/0.5.0/)
[0\.4.0 Mar 16, 2016](https://pypi.org/project/python-dotenv/0.4.0/)
[0\.3.0 Nov 4, 2015](https://pypi.org/project/python-dotenv/0.3.0/)
[0\.2.0 Oct 28, 2015](https://pypi.org/project/python-dotenv/0.2.0/)
[0\.1.5 Oct 8, 2015](https://pypi.org/project/python-dotenv/0.1.5/)
[0\.1.3 Aug 21, 2015](https://pypi.org/project/python-dotenv/0.1.3/)
[0\.1.2 Feb 28, 2015](https://pypi.org/project/python-dotenv/0.1.2/)
[0\.1.0 Sep 8, 2014](https://pypi.org/project/python-dotenv/0.1.0/)
## Download files
Download the file for your platform. If you're not sure which to choose, learn more about [installing packages](https://packaging.python.org/tutorials/installing-packages/ "External link").
### Source Distribution
[python\_dotenv-1.2.2.tar.gz](https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz) (50.1 kB [view details](https://pypi.org/project/python-dotenv/#python_dotenv-1.2.2.tar.gz))
Uploaded Mar 1, 2026 `Source`
### Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about [wheel file names](https://packaging.python.org/en/latest/specifications/binary-distribution-format/ "External link").
The dropdown lists show the available interpreters, ABIs, and platforms.
Enable javascript to be able to filter the list of wheel files.
Copy a direct link to the current filters <https://pypi.org/project/python-dotenv/#files> Copy
Showing 1 of 1 file.
File name
Interpreter
ABI
Platform
[python\_dotenv-1.2.2-py3-none-any.whl](https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl) (22.1 kB [view details](https://pypi.org/project/python-dotenv/#python_dotenv-1.2.2-py3-none-any.whl))
Uploaded Mar 1, 2026 `Python 3`
## File details
Details for the file `python_dotenv-1.2.2.tar.gz`.
### File metadata
- Download URL: [python\_dotenv-1.2.2.tar.gz](https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz)
- Upload date:
Mar 1, 2026
- Size: 50.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
### File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | `2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3` | Copy |
| MD5 | `74d7de20ea73ed77c5a0c2a5d9c39764` | Copy |
| BLAKE2b-256 | `82ed0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8` | Copy |
[See more details on using hashes here.](https://pip.pypa.io/en/stable/topics/secure-installs/#hash-checking-mode "External link")
### Provenance
The following attestation bundles were made for `python_dotenv-1.2.2.tar.gz`:
Publisher: [`release.yml` on theskumar/python-dotenv](https://github.com/theskumar/python-dotenv/blob/HEAD/.github/workflows/release.yml)
Attestations:
*Values shown here reflect the state when the release was signed and may no longer be current.*
- Statement:
- Statement type: <https://in-toto.io/Statement/v1>
- Predicate type: <https://docs.pypi.org/attestations/publish/v1>
- Subject name: `python_dotenv-1.2.2.tar.gz`
- Subject digest: `2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3`
- Sigstore transparency entry: [1006580280](https://search.sigstore.dev/?logIndex=1006580280)
- Sigstore integration time:
Mar 1, 2026, 4:00:23 PM
Source repository:
- Permalink: [`theskumar/python-dotenv@36004e0e34be7665ff2b11a8a4005144f76f176d`](https://github.com/theskumar/python-dotenv/tree/36004e0e34be7665ff2b11a8a4005144f76f176d)
- Branch / Tag: [`refs/tags/v1.2.2`](https://github.com/theskumar/python-dotenv/tree/refs/tags/v1.2.2)
- Owner: <https://github.com/theskumar>
- Access: `public`
Publication detail:
- Token Issuer: `https://token.actions.githubusercontent.com`
- Runner Environment: `github-hosted`
- Publication workflow: [`release.yml@36004e0e34be7665ff2b11a8a4005144f76f176d`](https://github.com/theskumar/python-dotenv/blob/36004e0e34be7665ff2b11a8a4005144f76f176d/.github/workflows/release.yml)
- Trigger Event: `release`
## File details
Details for the file `python_dotenv-1.2.2-py3-none-any.whl`.
### File metadata
- Download URL: [python\_dotenv-1.2.2-py3-none-any.whl](https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl)
- Upload date:
Mar 1, 2026
- Size: 22.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
### File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | `1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a` | Copy |
| MD5 | `3571e55b11e6f67fb1e2030bf65b54f7` | Copy |
| BLAKE2b-256 | `0bd71959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a` | Copy |
[See more details on using hashes here.](https://pip.pypa.io/en/stable/topics/secure-installs/#hash-checking-mode "External link")
### Provenance
The following attestation bundles were made for `python_dotenv-1.2.2-py3-none-any.whl`:
Publisher: [`release.yml` on theskumar/python-dotenv](https://github.com/theskumar/python-dotenv/blob/HEAD/.github/workflows/release.yml)
Attestations:
*Values shown here reflect the state when the release was signed and may no longer be current.*
- Statement:
- Statement type: <https://in-toto.io/Statement/v1>
- Predicate type: <https://docs.pypi.org/attestations/publish/v1>
- Subject name: `python_dotenv-1.2.2-py3-none-any.whl`
- Subject digest: `1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a`
- Sigstore transparency entry: [1006580281](https://search.sigstore.dev/?logIndex=1006580281)
- Sigstore integration time:
Mar 1, 2026, 4:00:24 PM
Source repository:
- Permalink: [`theskumar/python-dotenv@36004e0e34be7665ff2b11a8a4005144f76f176d`](https://github.com/theskumar/python-dotenv/tree/36004e0e34be7665ff2b11a8a4005144f76f176d)
- Branch / Tag: [`refs/tags/v1.2.2`](https://github.com/theskumar/python-dotenv/tree/refs/tags/v1.2.2)
- Owner: <https://github.com/theskumar>
- Access: `public`
Publication detail:
- Token Issuer: `https://token.actions.githubusercontent.com`
- Runner Environment: `github-hosted`
- Publication workflow: [`release.yml@36004e0e34be7665ff2b11a8a4005144f76f176d`](https://github.com/theskumar/python-dotenv/blob/36004e0e34be7665ff2b11a8a4005144f76f176d/.github/workflows/release.yml)
- Trigger Event: `release`
## Help
- [Installing packages](https://packaging.python.org/tutorials/installing-packages/ "External link")
- [Uploading packages](https://packaging.python.org/tutorials/packaging-projects/ "External link")
- [User guide](https://packaging.python.org/ "External link")
- [Project name retention](https://www.python.org/dev/peps/pep-0541/ "External link")
- [FAQs](https://pypi.org/help/)
## About PyPI
- [PyPI Blog](https://blog.pypi.org/ "External link")
- [Infrastructure dashboard](https://dtdg.co/pypi "External link")
- [Statistics](https://pypi.org/stats/)
- [Logos & trademarks](https://pypi.org/trademarks/)
- [Our sponsors](https://pypi.org/sponsors/)
## Contributing to PyPI
- [Bugs and feedback](https://pypi.org/help/#feedback)
- [Contribute on GitHub](https://github.com/pypi/warehouse "External link")
- [Translate PyPI](https://hosted.weblate.org/projects/pypa/warehouse/ "External link")
- [Sponsor PyPI](https://pypi.org/sponsors/)
- [Development credits](https://github.com/pypi/warehouse/graphs/contributors "External link")
## Using PyPI
- [Terms of Service](https://policies.python.org/pypi.org/Terms-of-Service/ "External link")
- [Report security issue](https://pypi.org/security/)
- [Code of conduct](https://policies.python.org/python.org/code-of-conduct/ "External link")
- [Privacy Notice](https://policies.python.org/pypi.org/Privacy-Notice/ "External link")
- [Acceptable Use Policy](https://policies.python.org/pypi.org/Acceptable-Use-Policy/ "External link")
***
Status: [all systems operational](https://status.python.org/ "External link")
Developed and maintained by the Python community, for the Python community.
[Donate today\!](https://donate.pypi.org/)
"PyPI", "Python Package Index", and the blocks logos are registered [trademarks](https://pypi.org/trademarks/) of the [Python Software Foundation](https://www.python.org/psf-landing).
ยฉ 2026 [Python Software Foundation](https://www.python.org/psf-landing/ "External link")
[Site map](https://pypi.org/sitemap/)
Switch to desktop version
Supported by
[ AWS Cloud computing and Security Sponsor](https://aws.amazon.com/) [ Datadog Monitoring](https://www.datadoghq.com/) [ Depot Continuous Integration](https://depot.dev/) [ Fastly CDN](https://www.fastly.com/) [ Google Download Analytics](https://careers.google.com/) [ Pingdom Monitoring](https://www.pingdom.com/) [ Sentry Error logging](https://sentry.io/for/python/?utm_source=pypi&utm_medium=paid-community&utm_campaign=python-na-evergreen&utm_content=static-ad-pypi-sponsor-learnmore) [ StatusPage Status page](https://statuspage.io/) |
| Readable Markdown | [](https://github.com/theskumar/python-dotenv/actions/workflows/test.yml) [](https://badge.fury.io/py/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](https://12factor.net/) principles.
- [Getting Started](https://pypi.org/project/python-dotenv/#getting-started)
- [Other Use Cases](https://pypi.org/project/python-dotenv/#other-use-cases)
- [Load configuration without altering the environment](https://pypi.org/project/python-dotenv/#load-configuration-without-altering-the-environment)
- [Parse configuration as a stream](https://pypi.org/project/python-dotenv/#parse-configuration-as-a-stream)
- [Load .env files in IPython](https://pypi.org/project/python-dotenv/#load-env-files-in-ipython)
- [Command-line Interface](https://pypi.org/project/python-dotenv/#command-line-interface)
- [File format](https://pypi.org/project/python-dotenv/#file-format)
- [Multiline values](https://pypi.org/project/python-dotenv/#multiline-values)
- [Variable expansion](https://pypi.org/project/python-dotenv/#variable-expansion)
- [Related Projects](https://pypi.org/project/python-dotenv/#related-projects)
- [Acknowledgements](https://pypi.org/project/python-dotenv/#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() # 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:
```
# 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](https://pypi.org/project/python-dotenv/#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](https://docs.python.org/3/library/io.html) 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.
### Disable load\_dotenv
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.
## 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. Reading from FIFOs (named pipes) on Unix systems is also supported.
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:
- 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
- [environs](https://github.com/sloria/environs)
- [Honcho](https://github.com/nickstenning/honcho)
- [dump-env](https://github.com/sobolevn/dump-env)
- [dynaconf](https://github.com/dynaconf/dynaconf)
- [parse\_it](https://github.com/naorlivne/parse_it)
- [django-dotenv](https://github.com/jpadilla/django-dotenv)
- [django-environ](https://github.com/joke2k/django-environ)
- [python-decouple](https://github.com/HBNetwork/python-decouple)
- [django-configuration](https://github.com/jezdez/django-configurations)
## Acknowledgements
This project is currently maintained by [Saurabh Kumar](https://saurabh-kumar.com/) and [Bertrand Bonnefoy-Claudet](https://github.com/bbc2) and would not have been possible without the support of these [awesome people](https://github.com/theskumar/python-dotenv/graphs/contributors).
## Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## \[v1.2.2\] - 2026-03-01
### Added
- Support for Python 3.14, including the free-threaded (3.14t) build. (\#)
### Changed
- The `dotenv run` command now forwards flags directly to the specified command by [@bbc2](https://github.com/bbc2) in [\#607](https://github.com/theskumar/python-dotenv/issues/607)
- Improved documentation clarity regarding override behavior and the reference page.
- Updated PyPy support to version 3.11.
- Documentation for FIFO file support.
- Dropped Support for Python 3.9.
### Fixed
- Improved `set_key` and `unset_key` behavior when interacting with symlinks by [@bbc2](https://github.com/bbc2) in [\#790c5](https://github.com/theskumar/python-dotenv/commit/790c5c02991100aa1bf41ee5330aca75edc51311)
- Corrected the license specifier and added missing Python 3.14 classifiers in package metadata by [@JYOuyang](https://github.com/JYOuyang) in [\#590](https://github.com/theskumar/python-dotenv/issues/590)
### Breaking Changes
- `dotenv.set_key` and `dotenv.unset_key` used to follow symlinks in some situations. This is no longer the case. For that behavior to be restored in all cases, `follow_symlinks=True` should be used.
- In the CLI, `set` and `unset` used to follow symlinks in some situations. This is no longer the case.
- `dotenv.set_key`, `dotenv.unset_key` and the CLI commands `set` and `unset` used to reset the file mode of the modified .env file to `0o600` in some situations. This is no longer the case: The original mode of the file is now preserved. Is the file needed to be created or wasn't a regular file, mode `0o600` is used.
## [1\.2.1](https://github.com/theskumar/python-dotenv/compare/v1.2.0...v1.2.1) - 2025-10-26
- Move more config to `pyproject.toml`, removed `setup.cfg`
- Add support for reading `.env` from FIFOs (Unix) by [@sidharth-sudhir](https://github.com/sidharth-sudhir) in [\#586](https://github.com/theskumar/python-dotenv/issues/586)
## [1\.2.0](https://github.com/theskumar/python-dotenv/compare/v1.1.1...v1.2.0) - 2025-10-26
- Upgrade build system to use PEP 517 & PEP 518 to use `build` and `pyproject.toml` by [@EpicWink](https://github.com/EpicWink) in [\#583](https://github.com/theskumar/python-dotenv/issues/583)
- Add support for Python 3.14 by [@23f3001135](https://github.com/23f3001135) in [\#579](https://github.com/theskumar/python-dotenv/pull/563)
- Add support for disabling of `load_dotenv()` using `PYTHON_DOTENV_DISABLED` env var. by [@matthewfranglen](https://github.com/matthewfranglen) in [\#569](https://github.com/theskumar/python-dotenv/issues/569)
## [1\.1.1](https://github.com/theskumar/python-dotenv/compare/v1.1.0...v1.1.1) - 2025-06-24
### Fixed
- CLI: Ensure `find_dotenv` work reliably on python 3.13 by [@theskumar](https://github.com/theskumar) in [\#563](https://github.com/theskumar/python-dotenv/pull/563)
- CLI: revert the use of execvpe on Windows by [@wrongontheinternet](https://github.com/wrongontheinternet) in [\#566](https://github.com/theskumar/python-dotenv/pull/566)
## [1\.1.0](https://github.com/theskumar/python-dotenv/compare/v1.0.1...v1.1.0) - 2025-03-25
**Feature**
- Add support for python 3.13
- Enhance `dotenv run`, switch to `execvpe` for better resource management and signal handling ([\#523](https://github.com/theskumar/python-dotenv/issues/523)) by [@eekstunt](https://github.com/eekstunt)
**Fixed**
- `find_dotenv` and `load_dotenv` now correctly looks up at the current directory when running in debugger or pdb ([\#553](https://github.com/theskumar/python-dotenv/issues/553) by [@randomseed42](https://github.com/zueve))
**Misc**
- Drop support for Python 3.8
## [1\.0.1](https://github.com/theskumar/python-dotenv/compare/v1.0.0...v1.0.1) - 2024-01-23
**Fixed**
- Gracefully handle code which has been imported from a zipfile ([\#456](https://github.com/theskumar/python-dotenv/issues/456) by [@samwyma](https://github.com/samwyma))
- Allow modules using `load_dotenv` to be reloaded when launched in a separate thread (\[\#497\] by [@freddyaboulton](https://github.com/freddyaboulton))
- Fix file not closed after deletion, handle error in the rewrite function ([\#469](https://github.com/theskumar/python-dotenv/issues/469) by [@Qwerty-133](https://github.com/Qwerty-133))
**Misc**
- Use pathlib.Path in tests ([\#466](https://github.com/theskumar/python-dotenv/issues/466) by [@eumiro](https://github.com/eumiro))
- Fix year in release date in changelog.md ([\#454](https://github.com/theskumar/python-dotenv/issues/454) by [@jankislinger](https://github.com/jankislinger))
- Use https in README links ([\#474](https://github.com/theskumar/python-dotenv/issues/474) by [@Nicals](https://github.com/Nicals))
## [1\.0.0](https://github.com/theskumar/python-dotenv/compare/v0.21.0...v1.0.0) - 2023-02-24
**Fixed**
- Drop support for python 3.7, add python 3.12-dev (\#449 by [@theskumar](https://github.com/theskumar))
- Handle situations where the cwd does not exist. (\#446 by [@jctanner](https://github.com/jctanner))
## [0\.21.1](https://github.com/theskumar/python-dotenv/compare/v0.21.0...v0.21.1) - 2023-01-21
**Added**
- Use Python 3.11 non-beta in CI (\#438 by [@bbc2](https://github.com/bbc2))
- Modernize variables code (\#434 by [@Nougat-Waffle](https://github.com/Nougat-Waffle))
- Modernize main.py and parser.py code (\#435 by [@Nougat-Waffle](https://github.com/Nougat-Waffle))
- Improve conciseness of cli.py and **init**.py (\#439 by [@Nougat-Waffle](https://github.com/Nougat-Waffle))
- Improve error message for `get` and `list` commands when env file can't be opened (\#441 by [@bbc2](https://github.com/bbc2))
- Updated License to align with BSD OSI template (\#433 by [@lsmith77](https://github.com/lsmith77))
**Fixed**
- Fix Out-of-scope error when "dest" variable is undefined (\#413 by [@theGOTOguy](https://github.com/theGOTOguy))
- Fix IPython test warning about deprecated `magic` (\#440 by [@bbc2](https://github.com/bbc2))
- Fix type hint for dotenv\_path var, add StrPath alias (\#432 by [@eaf](https://github.com/eaf))
## [0\.21.0](https://github.com/theskumar/python-dotenv/compare/v0.20.0...v0.21.0) - 2022-09-03
**Added**
- CLI: add support for invocations via 'python -m'. (\#395 by [@theskumar](https://github.com/theskumar))
- `load_dotenv` function now returns `False`. (\#388 by [@larsks](https://github.com/@larsks))
- CLI: add --format= option to list command. (\#407 by [@sammck](https://github.com/@sammck))
**Fixed**
- Drop Python 3.5 and 3.6 and upgrade GA (\#393 by [@eggplants](https://github.com/@eggplants))
- Use `open` instead of `io.open`. (\#389 by [@rabinadk1](https://github.com/@rabinadk1))
- Improve documentation for variables without a value (\#390 by [@bbc2](https://github.com/bbc2))
- Add `parse_it` to Related Projects (\#410 by [@naorlivne](https://github.com/@naorlivne))
- Update README.md (\#415 by [@harveer07](https://github.com/@harveer07))
- Improve documentation with direct use of MkDocs (\#398 by [@bbc2](https://github.com/bbc2))
## [0\.20.0](https://github.com/theskumar/python-dotenv/compare/v0.19.2...v0.20.0) - 2022-03-24
**Added**
- Add `encoding` (`Optional[str]`) parameter to `get_key`, `set_key` and `unset_key`. (\#379 by [@bbc2](https://github.com/bbc2))
**Fixed**
- Use dict to specify the `entry_points` parameter of `setuptools.setup` (\#376 by [@mgorny](https://github.com/mgorny)).
- Don't build universal wheels (\#387 by [@bbc2](https://github.com/bbc2)).
## [0\.19.2](https://github.com/theskumar/python-dotenv/compare/v0.19.1...v0.19.2) - 2021-11-11
**Fixed**
- In `set_key`, add missing newline character before new entry if necessary. (\#361 by [@bbc2](https://github.com/bbc2))
## [0\.19.1](https://github.com/theskumar/python-dotenv/compare/v0.19.0...v0.19.1) - 2021-08-09
**Added**
- Add support for Python 3.10. (\#359 by [@theskumar](https://github.com/theskumar))
## [0\.19.0](https://github.com/theskumar/python-dotenv/compare/v0.18.0...v0.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](https://github.com/bbc2)).
**Added**
- The `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](https://github.com/bbc2)).
- The `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](https://github.com/bbc2)).
## [0\.18.0](https://github.com/theskumar/python-dotenv/compare/v0.17.1...v0.18.0) - 2021-06-20
**Changed**
- Raise `ValueError` if `quote_mode` isn't one of `always`, `auto` or `never` in `set_key` (\#330 by [@bbc2](https://github.com/bbc2)).
- When writing a value to a .env file with `set_key` or `dotenv set <key> <value>` (\#330 by [@bbc2](https://github.com/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 by `string.isalnum`).
## [0\.17.1](https://github.com/theskumar/python-dotenv/compare/v0.17.0...v0.17.1) - 2021-04-29
**Fixed**
- Fixed tests for build environments relying on `PYTHONPATH` (\#318 by [@befeleme](https://github.com/befeleme)).
## [0\.17.0](https://github.com/theskumar/python-dotenv/compare/v0.16.0...v0.17.0) - 2021-04-02
**Changed**
- Make `dotenv get <key>` only show the value, not `key=value` (\#313 by [@bbc2](https://github.com/bbc2)).
**Added**
- Add `--override`/`--no-override` option to `dotenv run` (\#312 by [@zueve](https://github.com/zueve) and [@bbc2](https://github.com/bbc2)).
## [0\.16.0](https://github.com/theskumar/python-dotenv/compare/v0.15.0...v0.16.0) - 2021-03-27
**Changed**
- The default value of the `encoding` parameter for `load_dotenv` and `dotenv_values` is now `"utf-8"` instead of `None` (\#306 by [@bbc2](https://github.com/bbc2)).
- Fix resolution order in variable expansion with `override=False` (\#287 by [@bbc2](https://github.com/bbc2)).
## [0\.15.0](https://github.com/theskumar/python-dotenv/compare/v0.14.0...v0.15.0) - 2020-10-28
**Added**
- Add `--export` option to `set` to make it prepend the binding with `export` (\#270 by [@jadutter](https://github.com/jadutter)).
**Changed**
- Make `set` command create the `.env` file in the current directory if no `.env` file was found (\#270 by [@jadutter](https://github.com/jadutter)).
**Fixed**
- Fix potentially empty expanded value for duplicate key (\#260 by [@bbc2](https://github.com/bbc2)).
- Fix import error on Python 3.5.0 and 3.5.1 (\#267 by [@gongqingkui](https://github.com/gongqingkui)).
- Fix parsing of unquoted values containing several adjacent space or tab characters (\#277 by [@bbc2](https://github.com/bbc2), review by [@x-yuri](https://github.com/x-yuri)).
## [0\.14.0](https://github.com/theskumar/python-dotenv/compare/v0.13.0...v0.14.0) - 2020-07-03
**Changed**
- Privilege definition in file over the environment in variable expansion (\#256 by [@elbehery95](https://github.com/elbehery95)).
**Fixed**
- Improve error message for when file isn't found (\#245 by [@snobu](https://github.com/snobu)).
- Use HTTPS URL in package meta data (\#251 by [@ekohl](https://github.com/ekohl)).
## [0\.13.0](https://github.com/theskumar/python-dotenv/compare/v0.12.0...v0.13.0) - 2020-04-16
**Added**
- Add support for a Bash-like default value in variable expansion (\#248 by [@bbc2](https://github.com/bbc2)).
## [0\.12.0](https://github.com/theskumar/python-dotenv/compare/v0.11.0...v0.12.0) - 2020-02-28
**Changed**
- Use current working directory to find `.env` when bundled by PyInstaller (\#213 by [@gergelyk](https://github.com/gergelyk)).
**Fixed**
- Fix escaping of quoted values written by `set_key` (\#236 by [@bbc2](https://github.com/bbc2)).
- Fix `dotenv run` crashing on environment variables without values (\#237 by [@yannham](https://github.com/yannham)).
- Remove warning when last line is empty (\#238 by [@bbc2](https://github.com/bbc2)).
## [0\.11.0](https://github.com/theskumar/python-dotenv/compare/v0.10.5...v0.11.0) - 2020-02-07
**Added**
- Add `interpolate` argument to `load_dotenv` and `dotenv_values` to disable interpolation (\#232 by [@ulyssessouza](https://github.com/ulyssessouza)).
**Changed**
- Use logging instead of warnings (\#231 by [@bbc2](https://github.com/bbc2)).
**Fixed**
- Fix installation in non-UTF-8 environments (\#225 by [@altendky](https://github.com/altendky)).
- Fix PyPI classifiers (\#228 by [@bbc2](https://github.com/bbc2)).
## [0\.10.5](https://github.com/theskumar/python-dotenv/compare/v0.10.4...v0.10.5) - 2020-01-19
**Fixed**
- Fix handling of malformed lines and lines without a value (\#222 by [@bbc2](https://github.com/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](https://github.com/bbc2)).
## [0\.10.4](https://github.com/theskumar/python-dotenv/compare/v0.10.3...v0.10.4) - 2020-01-17
**Added**
- Make typing optional (\#179 by [@techalchemy](https://github.com/techalchemy)).
- Print a warning on malformed line (\#211 by [@bbc2](https://github.com/bbc2)).
- Support keys without a value (\#220 by [@ulyssessouza](https://github.com/ulyssessouza)).
## 0\.10.3
- Improve interactive mode detection ([@andrewsmith](https://github.com/andrewsmith))([\#183](https://github.com/theskumar/python-dotenv/issues/183)).
- Refactor parser to fix parsing inconsistencies ([@bbc2](https://github.com/bbc2))([\#170](https://github.com/theskumar/python-dotenv/issues/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](https://github.com/qnighy))([\#172](https://github.com/theskumar/python-dotenv/issues/172))
- `load_dotenv` and `dotenv_values` now accept an `encoding` parameter, defaults to `None` ([@theskumar](https://github.com/theskumar))([@earlbread](https://github.com/earlbread))(\[\#161\])
- Fix `str`/`unicode` inconsistency in Python 2: values are always `str` now. ([@bbc2](https://github.com/bbc2))([\#121](https://github.com/theskumar/python-dotenv/issues/121))
- Fix Unicode error in Python 2, introduced in 0.10.0. ([@bbc2](https://github.com/bbc2))([\#176](https://github.com/theskumar/python-dotenv/issues/176))
## 0\.10.1
- Fix parsing of variable without a value ([@asyncee](https://github.com/asyncee))([@bbc2](https://github.com/bbc2))([\#158](https://github.com/theskumar/python-dotenv/issues/158))
## 0\.10.0
- Add support for UTF-8 in unquoted values ([@bbc2](https://github.com/bbc2))([\#148](https://github.com/theskumar/python-dotenv/issues/148))
- Add support for trailing comments ([@bbc2](https://github.com/bbc2))([\#148](https://github.com/theskumar/python-dotenv/issues/148))
- Add backslashes support in values ([@bbc2](https://github.com/bbc2))([\#148](https://github.com/theskumar/python-dotenv/issues/148))
- Add support for newlines in values ([@bbc2](https://github.com/bbc2))([\#148](https://github.com/theskumar/python-dotenv/issues/148))
- Force environment variables to str with Python2 on Windows ([@greyli](https://github.com/greyli))
- Drop Python 3.3 support ([@greyli](https://github.com/greyli))
- Fix stderr/-out/-in redirection ([@venthur](https://github.com/venthur))
## 0\.9.0
- Add `--version` parameter to cli ([@venthur](https://github.com/venthur))
- Enable loading from current directory ([@cjauvin](https://github.com/cjauvin))
- Add 'dotenv run' command for calling arbitrary shell script with .env ([@venthur](https://github.com/venthur))
## 0\.8.1
- Add tests for docs ([@Flimm](https://github.com/Flimm))
- Make 'cli' support optional. Use `pip install python-dotenv[cli]`. ([@theskumar](https://github.com/theskumar))
## 0\.8.0
- `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.
- Add support for `export` prefix in the line.
- Internal refractoring ([@theskumar](https://github.com/theskumar))
- Allow `load_dotenv` and `dotenv_values` to work with `StringIO())` ([@alanjds](https://github.com/alanjds))([@theskumar](https://github.com/theskumar))([\#78](https://github.com/theskumar/python-dotenv/issues/78))
## 0\.7.1
- Remove hard dependency on iPython ([@theskumar](https://github.com/theskumar))
## 0\.7.0
- Add support to override system environment variable via .env. ([@milonimrod](https://github.com/milonimrod)) ([\#63](https://github.com/theskumar/python-dotenv/issues/63))
- Disable ".env not found" warning by default ([@maxkoryukov](https://github.com/maxkoryukov)) ([\#57](https://github.com/theskumar/python-dotenv/issues/57))
## 0\.6.5
- Add support for special characters `\`. ([@pjona](https://github.com/pjona)) ([\#60](https://github.com/theskumar/python-dotenv/issues/60))
## 0\.6.4
- Fix issue with single quotes ([@Flimm](https://github.com/Flimm)) ([\#52](https://github.com/theskumar/python-dotenv/issues/52))
## 0\.6.3
- Handle unicode exception in setup.py ([\#46](https://github.com/theskumar/python-dotenv/issues/46))
## 0\.6.2
- Fix dotenv list command ([@ticosax](https://github.com/ticosax))
- Add iPython Support ([@tillahoffmann](https://github.com/tillahoffmann))
## 0\.6.0
- Drop support for Python 2.6
- Handle escaped characters and newlines in quoted values. (Thanks [@iameugenejo](https://github.com/iameugenejo))
- Remove any spaces around unquoted key/value. (Thanks [@paulochf](https://github.com/paulochf))
- Added POSIX variable expansion. (Thanks [@hugochinchilla](https://github.com/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](https://github.com/isms))
## 0\.4.0
- cli: Added `-q/--quote` option to control the behaviour of quotes around values in `.env`. (Thanks [@hugochinchilla](https://github.com/hugochinchilla)).
- Improved test coverage. |
| Shard | 59 (laksa) |
| Root Hash | 7813724874982801459 |
| Unparsed URL | org,pypi!/project/python-dotenv/ s443 |