Skip to main content

xtr-dotenv

Layered .env files loaded into the environment, and the same layers behind a typed settings model.

python 3.11+ typed license MIT

Why?

Real applications keep several .env files layered so a developer laptop, a CI runner and a production host each end up with the settings that suit, without any one file knowing about the other. This library is the loader every layer runs through, plus a pydantic-settings source that feeds a typed model from the same cascade — without ever touching os.environ behind your back.

  • 📚 The layered cascade — .env → .env.local → .env.{env} → .env.{env}.local, with a .env.dist read instead of a missing .env, and real environment variables always winning.
  • 🧪 Testable end-to-end — hand the loader a plain dict and no other test in the same process can see anything it did.
  • 🧩 Pydantic-settings integration — DotenvSettings reads the same cascade from a sandboxed copy of os.environ, so a model gets the values without side effects.
  • 🌐 Variable expansion — $VAR, ${VAR}, ${VAR:-default}, ${VAR:=default}, \$ as a literal. Single-quoted values are literal too. $(command) is kept as text, never run.
  • ⚡ A dumped fast path — dotenv:dump writes the compiled cascade to .env.local.json; boot_env reads that one file instead of the cascade.

Install

uv add xtr-dotenv                           # the loader and the settings source
uv add xtr-dotenv xtr-dependency-injection  # + the container, for the DotenvBundle
uv add xtr-console                          # beside it: + the dotenv:dump and debug:dotenv commands

Requires Python 3.11+. Depends on pydantic-settings, python-dotenv, typing-extensions and anyio — not on the container: the bundle is used when xtr-dependency-injection is installed beside the package, never as an extra, and the loader works without it. The two commands also need xtr-console installed beside it.

Quick start

Call Dotenv().boot_env(...) at the very top of your entry point — before anything reads a settings model, and before you build a kernel:

from pathlib import Path

from xtr_dotenv import Dotenv

Dotenv().boot_env(str(Path(__file__).parent / ".env"))

# ... only now import the kernel, settings, etc.
from app.kernel import kernel

raise SystemExit(kernel.run(...))

boot_env also sets APP_DEBUG to "1" or "0": its own value read as a flag when it is set, otherwise on in every environment but those in prod_envs — Dotenv(prod_envs=("prod", "staging")), ("prod",) by default.

The loader is stateless: hand it a MutableMapping[str, str] as environ= and no other code sees a thing.

sandbox: dict[str, str] = {}
Dotenv(environ=sandbox).load_env("/etc/app/.env")

The file cascade

load_env(path) reads, in order:

Order File When it applies
1 path Always, or path.dist when path is missing
2 (reads env key from environ; an unset or empty one takes default_env)
3 path.local Only outside test_envs — a developer's per-machine overrides
4 (re-reads env key) The .local file may have set a different environment
5 path.{env} When env is not "local"
6 path.{env}.local Same — a per-machine override for that environment

Files 5 and 6 were chosen by the environment, so one of them naming a different environment is a FormatError pointing at the line. cascade(path) returns the environment and these files, without loading anything — what debug:dotenv lists.

Later files override earlier ones. A real environment variable always wins over any file unless override_existing_vars=True is passed — overload() passes it — and then the file's value replaces it, the real one is gone, and the name counts as one a file set. XTR_DOTENV_VARS tracks which names came from a file so a later file may replace them; XTR_DOTENV_PATH records the base path so tooling can find it.

Its value being empty changes nothing: FOO= is how a process says "disabled", and no file undoes it. The env key is the one exception — an empty one names no environment, so the cascade defaults it and may write that default back.

Variable expansion

Written Means
$VAR, ${VAR} the value of VAR, or empty when unset
${VAR:-default} default when VAR is unset or empty
${VAR:=default} the same, and record VAR=default for later lookups
\$ a literal dollar sign

Single-quoted values are never expanded — that is the escape hatch for a literal $ inside a password. $(command) is kept as text and never run: a settings loader should do no I/O beyond reading files. A default is plain text — a quote, a brace or a $ in one (${A:-${B}}), or a ${ never closed, is a FormatError naming the line. A value spanning lines must be quoted.

Expansion runs once every file of the cascade is read, so a value in .env may reference one only .env.local defines; a real environment variable wins inside an expansion as it does everywhere else. A self-referencing A=${A:-x} reads the value A has now (or the default) — it does not cycle. Expansion repeats as long as each pass resolves something, so a chain of references resolves however long it is; values left waiting on each other are a real cycle and raise VariableCircularReferenceError.

Typed settings from the cascade

DotenvSettings is a BaseSettings base whose subclass reads the layered cascade from a sandboxed copy of os.environ:

from typing import ClassVar

from xtr_dotenv import DotenvSettings


class AppSettings(DotenvSettings):
    _dotenv_path: ClassVar[str] = "/etc/app/.env"
    _dotenv_env_key: ClassVar[str] = "APP_ENV"
    _dotenv_default_env: ClassVar[str] = "prod"

    database_url: str
    log_level: str = "INFO"

Source priority is: init keyword arguments > real environment variables > the dotenv cascade > secret files > field defaults. No file the source reads writes into os.environ.

Errors

Everything the library raises derives from DotenvError, and carries the data as typed attributes.

Error Raised when
FormatError A line cannot be parsed (bad binding, key without =); carries .path, .line, .reason
InvalidArgumentError A DotenvConfig field is empty; carries .reason
PathError A file cannot be read, or the dump cannot be written; carries .path
VariableCircularReferenceError Variables reference each other and never resolve; carries .names

FormatError, InvalidArgumentError and VariableCircularReferenceError are also ValueErrors; PathError is also OSError. Existing except blocks keep working.

Use in an application

Everything adding this package to an application on xtr-dependency-injection takes — and, read backwards, what removing it undoes.

  • Install — uv add xtr-dotenv xtr-dependency-injection: the bundle needs the container installed beside it, never as an extra. Install xtr-console beside it for the dotenv:dump and debug:dotenv commands.
  • Recipe — uv run xtr-recipes recipes:sync does the Activate, Environment and Ignore steps below: it lists DotenvBundle, writes APP_ENV=dev in .env, and ignores the per-machine .env.local, .env.*.local and .env.local.json. It prints the Load step, which a recipe cannot make for you.
  • Load — the bundle does not load .env files. Call Dotenv().boot_env(...) at the top of every entry point, before the kernel is built — see Quick start.
  • Activate — DotenvBundle: {"all": True} in BUNDLES in <app>/config/bundles.py, imported from xtr_dotenv.bundle. It only adds dotenv:dump and debug:dotenv, and only when the console bundle is active.
  • Brings along — nothing.
  • Configure — optional: with no configuration the base file is %kernel.project_dir%/.env and the environment is read from APP_ENV. <app>/config/packages/dotenv.py, a @configure function returning DotenvConfig, changes them — see Kernel / bundle.
  • Environment — create .env with the defaults every machine shares, for example APP_ENV=dev, and commit it.
  • Ignore — .env.local, .env.*.local and .env.local.json: per-machine overrides, and what dotenv:dump writes.
  • Remove — drop the BUNDLES entry and every boot_env(...) call, delete <app>/config/packages/dotenv.py, then uv remove xtr-dotenv. The .env files stay yours.
  • Check — debug:dotenv reports the environment, production and debug flags, and lists each file of the cascade as loaded or missing (values masked unless --show-values).

Kernel / bundle

With xtr-dependency-injection installed beside the package — it is not a dependency, and nothing outside xtr_dotenv.bundle and the commands it loads needs it — an application lists DotenvBundle in its app/config/bundles.py. The bundle does not load .env files — Dotenv().boot_env(...) runs before the kernel is built. What the bundle contributes is the two commands that need the kernel to know its project directory:

uv add xtr-dotenv xtr-dependency-injection xtr-console
# app/config/bundles.py
from xtr_dotenv.bundle import DotenvBundle

BUNDLES = {DotenvBundle: {"all": True}}
# app/config/packages/dotenv.py
from xtr_dependency_injection import configure
from xtr_dotenv.bundle import DotenvConfig


@configure
def dotenv() -> DotenvConfig:
    return DotenvConfig(path="%kernel.project_dir%/.env", env_key="APP_ENV")
DotenvConfig field Meaning
path The base .env path; default %kernel.project_dir%/.env — parameter references are resolved by the kernel, and a relative path is taken from the project directory
env_key The variable naming the active environment
debug_key The variable naming debug mode
test_envs Environments where the .local overlay is skipped
prod_envs Environments considered production, used for debug defaulting

Commands

Command What it does
dotenv:dump [env] Compile the cascade for env (default: the kernel's env) into <path>.local.json. Runs on a fresh environ with only the env key, so real environment variables never land in the dump — but the .local files do, so gitignore it
debug:dotenv [name] [--show-values] Report the environment, whether it is production (prod_envs) and the debug flag (debug_key), list the files the loader's own cascade considers (loaded / missing) and each variable's value per file, filtered by name when given. Values are masked unless --show-values is passed

The commands are only registered when the console bundle is active — xtr-console installed beside the package; on a headless application the bundle is still valid and boots at zero config.

Layout

xtr_dotenv/
├── dotenv.py                       the loader: parse, load, overload, populate, load_env, boot_env
├── dotenv_settings_source.py       a pydantic-settings source that runs the cascade in a sandbox
├── dotenv_settings.py              BaseSettings base declaring the cascade behind the real env
├── exception/                      DotenvError + FormatError, InvalidArgumentError, PathError, …
├── command/                        dotenv:dump and debug:dotenv (xtr-console commands)
└── bundle/                         DotenvBundle for xtr-dependency-injection

Development

Developed in the python-xtr monorepo, under packages/xtr-dotenv; run the commands below from there. The python-xtr-dotenv repository is a read-only copy, so send issues and pull requests to the monorepo.

uv sync
uv run ruff check
uv run ruff format --check
uv run basedpyright
uv run ty check
uv run pytest

License

MIT — see LICENSE.

Metadata

Release files for xtr-dotenv 5.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xtr-dotenv 5.2.1
File Size Uploaded Provenance Actions
xtr_dotenv-5.2.1.tar.gz 29.0 kB With provenance Details for xtr_dotenv-5.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xtr-dotenv 5.2.1
File Interpreter ABI Platform Actions
xtr_dotenv-5.2.1-py3-none-any.whl Python 3 none any Details for xtr_dotenv-5.2.1-py3-none-any.whl

Total release size: 64.7 kB

Release files / xtr_dotenv-5.2.1.tar.gz

Download URL xtr_dotenv-5.2.1.tar.gz
Size 29.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b1fe051c2d98fe8ced00a223d56820ef26481d2eb3cabf7a3d6878e86e5ef4b2
BLAKE2b-256 checksum
How to use checksums
616d8a9366760aa5a5c418aed62a7ad91857a4a75d65bc3e2c5057c5d2055737
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / xtr_dotenv-5.2.1-py3-none-any.whl

Download URL xtr_dotenv-5.2.1-py3-none-any.whl
Size 35.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
23c1cbf87defa9d6c800e59c43b573416064b97dbc4647266045c97d8efafcce
BLAKE2b-256 checksum
How to use checksums
733f7c9340b943beb249a60135b1fe5eaf59ab6be78ecdaadeb4df6018e8f944
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for xtr-dotenv 5.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xtr_dotenv-5.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page