xtr-dotenv
Layered .env files loaded into the environment, and the same layers behind a typed settings model.
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.distread instead of a missing.env, and real environment variables always winning. - 🧪 Testable end-to-end — hand the loader a plain
dictand no other test in the same process can see anything it did. - 🧩 Pydantic-settings integration —
DotenvSettingsreads the same cascade from a sandboxed copy ofos.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:dumpwrites the compiled cascade to.env.local.json;boot_envreads 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 thedotenv:dumpanddebug:dotenvcommands. - Recipe —
uv run xtr-recipes recipes:syncdoes the Activate, Environment and Ignore steps below: it listsDotenvBundle, writesAPP_ENV=devin.env, and ignores the per-machine.env.local,.env.*.localand.env.local.json. It prints the Load step, which a recipe cannot make for you. - Load — the bundle does not load
.envfiles. CallDotenv().boot_env(...)at the top of every entry point, before the kernel is built — see Quick start. - Activate —
DotenvBundle: {"all": True}inBUNDLESin<app>/bundles.py, imported fromxtr_dotenv.bundle. It only addsdotenv:dumpanddebug:dotenv, and only when the console bundle is active. - Brings along — nothing.
- Configure — optional: with no configuration the base file is
%kernel.project_dir%/.envand the environment is read fromAPP_ENV.<app>/config/dotenv.py, a@configurefunction returningDotenvConfig, changes them — see Kernel / bundle. - Environment — create
.envwith the defaults every machine shares, for exampleAPP_ENV=dev, and commit it. - Ignore —
.env.local,.env.*.localand.env.local.json: per-machine overrides, and whatdotenv:dumpwrites. - Remove — drop the
BUNDLESentry and everyboot_env(...)call, delete<app>/config/dotenv.py, thenuv remove xtr-dotenv. The.envfiles stay yours. - Check —
debug:dotenvreports 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/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/bundles.py
from xtr_dotenv.bundle import DotenvBundle
BUNDLES = {DotenvBundle: {"all": True}}
# app/config/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.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xtr_dotenv-5.0.0.tar.gz | 29.1 kB | With provenance | Details for xtr_dotenv-5.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_dotenv-5.0.0-py3-none-any.whl | Python 3 | none | any | Details for xtr_dotenv-5.0.0-py3-none-any.whl |
Total release size: 64.7 kB
Release files / xtr_dotenv-5.0.0.tar.gz
| Download URL | xtr_dotenv-5.0.0.tar.gz |
|---|---|
| Size | 29.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4abb7610d7aa443195afd4b8dac84fb871f5351577092b33fa58d052f23c6e3d
|
|
BLAKE2b-256 checksum How to use checksums |
8b4c4e6f3d95ee8b4f387c1c883d3ed9b2506b5dfe5fe2897d31ec0a7e99bab6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 logRelease files / xtr_dotenv-5.0.0-py3-none-any.whl
| Download URL | xtr_dotenv-5.0.0-py3-none-any.whl |
|---|---|
| Size | 35.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e2ae54079a27b73da9e2f2d659f05fc3f0b1af7167fe4900ea57a8316262e202
|
|
BLAKE2b-256 checksum How to use checksums |
3510a75e423ac95341e3c3a5572e2ae92426e114164638de77bc2c8b5594ef90
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 logSecurity for xtr-dotenv 5.0.0
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.
Attestation for xtr_dotenv-5.0.0.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 logA 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.