python-dotenv

python-dotenv

python-dotenv reads key-value pairs from a .env file and can set them as environment variables. It helps in the development of applications following the 12-factor principles.

• Getting Started
• Other Use Cases
  • 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": "[e-mail]"}

This notably enables advanced configuration management:

import os
from dotenv import dotenv_values

config = {
    **dotenv_values(".env.shared"),  # load shared development variables
    **dotenv_values(".env.secret"),  # load sensitive variables
    **os.environ,  # override loaded values with environment variables
}

Parse configuration as a stream

load_dotenv and dotenv_values accept streams via their stream argument. It is thus possible to load the variables from sources other than the filesystem (e.g. the network).

from io import StringIO

from dotenv import load_dotenv

config = StringIO("USER=foo\nEMAIL=[e-mail]")
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 [e-mail]
$ dotenv list
USER=foo
EMAIL=[e-mail]
$ dotenv list --format=json
{
  "USER": "foo",
  "EMAIL": "[e-mail]"
}
$ 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.