pytest-env

Warnings

• breaking Python 3.9 support was dropped in `pytest-env` version 1.2.0. Users on Python 3.9 or earlier must upgrade their Python version to at least 3.10. Note that `pytest` itself also dropped Python 3.9 support in version 9.0.0.
  Fix: Upgrade to Python 3.10 or newer.
• gotcha Configuration precedence: When multiple configuration formats are present, TOML native formats (`pytest.toml`, `.pytest.toml`, `pyproject.toml`) take precedence over INI format (`pytest.ini`). Among TOML files, `pytest.toml`, then `.pytest.toml`, then `pyproject.toml` is checked, stopping at the first file with a `pytest_env` section. Additionally, configured `env_files` are loaded before inline variables, so inline configuration takes precedence over `.env` files.
  Fix: Be mindful of the configuration file hierarchy and how inline variables override `.env` file contents. Use `--pytest-env-verbose` for debugging source attribution.
• gotcha Behavior of `--envfile` CLI option: The `--envfile PATH` (override) mode loads *only* the specified file, ignoring all `env_files` configured in `pyproject.toml` or `pytest.ini`. The `--envfile +PATH` (extend) mode loads configured `env_files` first, then loads the CLI-specified file, allowing it to override configured variables. Unlike configured `env_files`, CLI-specified files *must* exist, otherwise a `FileNotFoundError` will be raised.
  Fix: Explicitly choose between override (`PATH`) and extend (`+PATH`) modes based on desired behavior. Ensure that any file specified via `--envfile` exists.
• gotcha Environment variable preservation (D: flag/default=true): Prior to version 1.6.0, environment variables defined in configuration would unconditionally overwrite existing environment variables set outside pytest. As of 1.6.0, `pytest-env` by default *preserves* existing environment variables unless explicitly told to overwrite. For older versions or explicit control, use the `D:` prefix in INI format (e.g., `D:VAR=value`) or `default = true` in TOML to set a variable only if it's not already defined.
  Fix: For versions <1.6.0, use the `D:` prefix or `default=true` if you wish to preserve existing variables. For 1.6.0+, understand that existing variables are preserved by default, but you can explicitly override them by omitting `D:` or `default=true`.
• gotcha Unsetting environment variables (U: flag/unset=true): To remove an environment variable entirely within a test session, use the `U:` prefix in INI format (e.g., `U:VAR`) or `unset = true` in TOML format. This feature was added in version 1.3.0.
  Fix: Upgrade to `pytest-env` 1.3.0 or newer to use the unsetting functionality.

Install

• pip install pytest-env Install stable version

Imports

• pytest-env plugin

  Functionality is automatically loaded by pytest via entry points.

  pytest-env is a plugin; you typically don't import symbols from it directly in your test code for its primary function. Its configuration is handled in `pyproject.toml`, `pytest.ini`, etc.

Quickstart

Configure environment variables in your `pyproject.toml` (or `pytest.ini`). The plugin will automatically make these variables available to your tests via `os.environ`. You can use `transform = true` in TOML (or by default in INI) to enable variable expansion like `${VAR:-default}`. Use `--pytest-env-verbose` to debug how variables are assigned.

# pyproject.toml
[tool.pytest_env]
DATABASE_URL = "postgresql://localhost/test_db"
DEBUG = "true"
MY_API_KEY = "${MY_API_KEY:-default_key}"

# tests/test_my_app.py
import os

def test_database_connection():
    assert os.environ["DATABASE_URL"] == "postgresql://localhost/test_db"
    assert os.environ["DEBUG"] == "true"

def test_api_key():
    # MY_API_KEY will be expanded using existing env var or default_key
    assert "MY_API_KEY" in os.environ
    print(f"API Key: {os.environ['MY_API_KEY']}")

# Run from your terminal:
# pytest
# To see verbose output of env var assignments:
# pytest --pytest-env-verbose