python-dotenv

python-dotenv reads key-value pairs from a .env file and sets them as environment variables, letting Python applications follow 12-factor-app configuration practices without hand-rolling a parser. A single load_dotenv() call at process startup is enough to make .env values available through os.environ exactly as if they had been exported in the shell, while dotenv_values() offers a non-mutating variant that returns a plain dict for more deliberate configuration layering.

Beyond the two core functions, the library ships variable expansion (${VAR} interpolation with fallback to the real environment), multiline and quoted values, a dotenv CLI for inspecting and editing .env files from the shell, and an IPython/Jupyter magic extension. It has no runtime dependencies for its core API, is fully typed (PEP 561 py.typed), and has been the de facto standard for environment-based configuration in the Python ecosystem for over a decade.

What You Get

• load_dotenv() to parse a .env file and merge its values into os.environ, with override controlling precedence against variables already set
• dotenv_values() for a non-mutating read that returns a dict, enabling layered configs (e.g. {**dotenv_values('.env.shared'), **dotenv_values('.env.secret'), **os.environ})
• POSIX-style variable expansion (${DOMAIN}) so values can reference each other or fall back to real environment variables
• A dotenv command-line tool (pip install "python-dotenv[cli]") to get/set/list/run against a .env file without opening an editor
• An IPython/Jupyter %dotenv magic for loading environment files inside notebooks
• Support for multiline, quoted, and FIFO-stream values, with clear parse-error warnings for malformed lines

Common Use Cases

• Loading local development secrets (API keys, database URLs) from a git-ignored .env file at app startup
• Layering shared and secret configuration files before falling back to real environment variables in staging/production
• Feeding environment variables into Django, Flask, FastAPI, or any framework that reads config via os.environ
• Driving reproducible local scripts and IPython notebooks without leaking credentials into shell history
• Wrapping subprocess invocations with dotenv run -- <command> so tools that expect a real environment work unmodified

Under The Hood

Architecture - The codebase separates parsing from application: parser.py tokenizes a .env stream into Binding records (key, value, original source line, error flag) using a small set of compiled regexes for quoted/unquoted keys and values, variables.py resolves ${VAR} interpolation against already-parsed bindings and os.environ, and main.py’s DotEnv class orchestrates file/stream reading, invalid-line warnings, and the public load_dotenv/dotenv_values/get_key/set_key/unset_key/find_dotenv functions. cli.py and ipython.py are thin wrappers around that same core, so the CLI and Jupyter magic share identical parsing behavior with the library API.

Tech Stack - Pure Python with no third-party runtime dependencies for the core API; the only optional dependency is click, pulled in solely via the [cli] extra for the dotenv command-line tool. The package is fully typed (py.typed marker for PEP 561), builds with setuptools, targets Python 3.10+, and is linted with ruff and type-checked with mypy per the repo’s ruff.toml/pyproject.toml configuration.

Code Quality - The tests/ directory contains roughly 77 test functions across ten files covering the parser, variable expansion, CLI, IPython integration, FIFO streams, and zip-import edge cases, with pyproject.toml configuring coverage reporting via tool.coverage. Naming is consistent and narrow (single-purpose modules for parsing, variables, and CLI), and the public functions are fully type-annotated, giving strong static-analysis coverage for a project of this size.

API Design - The library optimizes hard for a one-line getting-started path: from dotenv import load_dotenv; load_dotenv() is the entire integration for the common case, with dotenv_values() offered as a symmetric non-mutating alternative for teams that want to layer configuration explicitly rather than mutate os.environ implicitly. Function names (load_dotenv, get_key, set_key, unset_key, find_dotenv) read as a coherent CRUD-like vocabulary, and the README leads with copy-pasteable examples for every use case rather than requiring readers to infer usage from a reference doc.