fast-dotenv-rs

A fast Rust-backed drop-in replacement for python-dotenv==1.2.2, built with PyO3 and Maturin. It preserves the dotenv Python API, CLI, IPython extension, interpolation rules, and file mutation behavior.

中文说明

from dotenv import dotenv_values, load_dotenv

load_dotenv()
config = dotenv_values(".env")

The distribution is named fast-dotenv-rs, but existing application code keeps importing dotenv.

Why this project

• Low migration cost: keep from dotenv import load_dotenv and the dotenv CLI.
• Verifiable compatibility: run the complete pinned python-dotenv==1.2.2 upstream suite, not only basic KEY=value examples.
• Reproducible performance evidence: compare candidate and Oracle in isolated processes and validate values, types, and ordering before timing.
• Cross-platform packaging: build abi3 wheels with PyO3 and Maturin.

Status

Version 0.1.1 is the formal-release line. It makes Click a default dependency so a plain public install provides the complete dotenv CLI. The release workflow builds five native wheels and one sdist, publishes that immutable set through Trusted Publishing, then reinstalls the base public package and passes the full upstream compatibility suite on every advertised platform before creating the formal GitHub Release. Until those public links exist, the release remains blocked.

GitHub Actions CI #3 passed all four jobs:

The local Linux x86-64 / CPython 3.12 upstream result is:

218 passed, 1 skipped, 0 failed

The single Linux skip is an upstream platform/root condition. IPython was installed, so all three upstream IPython tests ran.

Installation

After the 0.1.1 public release exists, install the package with:

python -m pip install "fast-dotenv-rs==0.1.1"

Application code continues importing dotenv. To build from source instead:

git clone https://github.com/lowmiaq-gmail/fast-dotenv-rs.git
cd fast-dotenv-rs
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
python -m pip install -U pip maturin
maturin develop --release

Build a wheel:

maturin build --release --out wheelhouse
python -m pip install wheelhouse/*.whl

Do not install the Oracle in the same environment

Both python-dotenv and this project provide the top-level dotenv package and the dotenv command. Installing both in one environment causes the last installed distribution to overwrite the other. Use separate virtual environments for candidate/Oracle comparisons.

Compatible surface

Top-level exports match python-dotenv==1.2.2:

from dotenv import (
    dotenv_values, find_dotenv, get_cli_string, get_key,
    load_dotenv, load_ipython_extension, set_key, unset_key,
)

The compatibility surface also includes:

• dotenv.main.DotEnv, rewrite, and resolve_variables;
• parser Binding, Original, Reader, Position, and parser functions;
• variable Atom, Literal, Variable, and parse_variables;
• CLI list, set, get, unset, and run;
• dotenv.ipython.IPythonDotEnv and the %dotenv magic.

See docs/UPSTREAM-CONTRACT.md for signatures, return values, logging, exceptions, filesystem effects, and environment behavior.

CLI

dotenv list
dotenv list --format=json
dotenv set DATABASE_URL 'postgres://localhost/app'
dotenv get DATABASE_URL
dotenv unset DATABASE_URL
dotenv run -- python app.py
python -m dotenv --version

Reproduce the compatibility gates

python -m pip install "pytest>=8,<9" "click>=5" "ipython>=8"
cargo test --all-targets
PYTHONPATH=python python -m pytest -q tests
bash scripts/run_upstream_full.sh
PYTHONPATH=python python scripts/run_differential.py

The upstream runner pins and verifies the official python-dotenv==1.2.2 sdist and every upstream test fixture hash. It also checks that the candidate, not an installed Oracle, owns the imported dotenv namespace.

Benchmark snapshot

On one Linux x86-64 / CPython 3.12 machine, isolated-process dotenv_values() in-memory parsing workloads measured 15.957×–88.609× faster. The harness checks the return type, item order, and values before timing.

python tests/benchmark.py --repeats 7 --warmup 2 --iterations 1000

These numbers do not represent file I/O, process startup, macOS, Windows, or every application workload. See BENCHMARK.md for inputs, raw context, and limitations.

Documentation

• FULL-RELEASE-REPORT.md — current evidence and remaining release gates;
• docs/COMPATIBILITY.md — compatibility matrix;
• docs/UPSTREAM-CONTRACT.md — pinned upstream contract;
• docs/REUSE-AUDIT.md — reuse and license audit;
• docs/LAUNCH-SEO.md — launch, discovery, and adoption plan.
• docs/LAUNCH-STATUS.md — evidence-backed public launch status and review checkpoints.

License

Rust/PyO3 project code is MIT licensed. BSD-3-Clause notices for the upstream compatibility baseline are recorded in THIRD_PARTY_NOTICES.md and licenses/.