uv Environment Variables and .env Files

uv run loads dotenv files only when requested with --env-file or UV_ENV_FILE. Later files override earlier files, but a variable exported by the shell wins over every file. That order supports a shared base plus a local override without letting dotenv replace CI secrets.

Run a synthetic precedence check

APP_MODE=base
API_ORIGIN=https://base.example.invalid

APP_MODE=local

uv run --env-file base.env --env-file local.env -- \
  python -c 'import os; print(os.environ["APP_MODE"], os.environ["API_ORIGIN"])'

local https://base.example.invalid

APP_MODE=ci uv run --env-file base.env --env-file local.env -- \
  python -c 'import os; print(os.environ["APP_MODE"])'

ci

Multiple paths in UV_ENV_FILE are space-separated. Repeated flags keep ordering visible and avoid ambiguity when paths contain spaces.

Disable dotenv loading explicitly

Use --no-env-file when a command must consume only its inherited environment. Set UV_NO_ENV_FILE=1 for the equivalent policy in CI. Both disable files requested through the flag or UV_ENV_FILE.

APP_MODE=ci uv run --no-env-file -- \
  python -c 'import os; print(os.environ.get("APP_MODE"))'

# Expected output: ci

uv settings are not application variables

[tool.uv] in pyproject.toml configures uv itself: indexes, resolution, Python choices, and package behavior. It does not define APP_MODE for Python. Application values belong in the shell, a selected dotenv file, or the deployment platform.

uv discovers project configuration from the current directory upward. In a workspace, it starts at the workspace root and ignores member configuration because the workspace is locked as one unit. Run automation from a stable directory or pass an unambiguous env-file path.

Limitations

• dotenv values are strings; parse booleans and numbers in application code.
• Do not commit secret-bearing files. Commit a synthetic .env.example.
• uv run does not configure unrelated shells or already-running processes.
• uv configuration precedence and application environment precedence are separate systems.

The Python environments guide places uv beside venv and Poetry. Check files with the env validator or create a template with the env config builder.

Version scope and primary references

The precedence examples were observed with uv 0.8.17 and CPython 3.13.7 on September 14, 2026, in an isolated directory without a project. Other behavior follows the linked documentation reviewed on that date. Pin uv in reproducible CI and check the reference for your installed release.

• uv environment variable files
• uv run CLI reference
• UV_NO_ENV_FILE reference