pytest-env

1.6.0 verified Tue May 12 auth: no python install: stale

pytest-env is a pytest plugin that allows users to define and manage environment variables for their tests directly within configuration files such as `pyproject.toml`, `pytest.toml`, `.pytest.toml`, or `pytest.ini`. It also supports loading variables from `.env` files and via command-line options. The library is actively maintained, with frequent releases to add features and address issues. The current version is 1.6.0.

pip install pytest-env

Common errors

error PytestUnknownConfigurationWarning: Unknown config option: env ↓

cause The 'pytest-env' plugin is either not installed, or pytest is not recognizing the 'env' configuration option, often because it's placed in an incorrect section of the configuration file.

fix

Install the plugin using pip install pytest-env. Ensure the env configuration is placed under [pytest] in pytest.ini or .pytest.toml, or under [tool.pytest.ini_options] in pyproject.toml.

error ERROR: unknown option: --env ↓

cause The command-line option for setting environment variables with `pytest-env` is `--env-var`, not `--env`.

fix

Use pytest --env-var KEY=VALUE to set environment variables from the command line.

error ValueError: Invalid configuration line for env: 'KEY:VALUE' ↓

cause The environment variable definition in the configuration file (e.g., `pytest.ini`, `pyproject.toml`) uses an incorrect format, such as a colon instead of an equals sign, or improper quoting.

fix

Ensure environment variables are defined using KEY=VALUE format, with proper quoting if values contain spaces or special characters, for example: MY_VAR=my_value or MY_VAR="value with spaces".

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.

gotcha When configuring `pytest-env`, ensure TOML-formatted sections like `[tool.pytest_env]` are placed in appropriate configuration files (e.g., `pyproject.toml`, `pytest.toml`, `pytest.ini`) and not directly in Python script files (`.py`). Placing TOML syntax directly in a Python file will result in a `NameError`. ↓

fix Place `pytest-env` configuration in recognized project configuration files (`pyproject.toml`, `pytest.toml`, `pytest.ini`) according to their respective formats (TOML or INI), and do not embed them directly into Python scripts.

gotcha Configuration files like `pyproject.toml` or `pytest.ini` use specific markup (TOML or INI) and are not executable Python scripts. Attempting to place TOML/INI configuration syntax directly into a `.py` file will result in syntax errors or `NameError` if interpreted as Python code. ↓

fix Ensure `pytest-env` configuration (e.g., `[tool.pytest_env]`) is placed in a dedicated TOML file (`pyproject.toml`, `pytest.toml`) or INI file (`pytest.ini`), not directly inside Python scripts.

Install compatibility stale last tested: 2026-05-12 v1.1.5 installed · v1.6.0 latest

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - - 30.8M - broken

3.10 alpine (musl) - - - - - -

3.10 slim (glibc) wheel 2.7s - 31M - broken

3.10 slim (glibc) - - - - - -

3.11 alpine (musl) wheel - - 33.8M - broken

3.11 alpine (musl) - - - - - -

3.11 slim (glibc) wheel 2.6s - 34M - broken

3.11 slim (glibc) - - - - - -

3.12 alpine (musl) wheel - - 25.4M - broken

3.12 alpine (musl) - - - - - -

3.12 slim (glibc) wheel 2.6s - 26M - broken

3.12 slim (glibc) - - - - - -

3.13 alpine (musl) wheel - - 25.2M - broken

3.13 alpine (musl) - - - - - -

3.13 slim (glibc) wheel 2.5s - 26M - broken

3.13 slim (glibc) - - - - - -

3.9 alpine (musl) wheel - - 30.0M - broken

3.9 alpine (musl) - - - - - -

3.9 slim (glibc) wheel 3.0s - 30M - broken

3.9 slim (glibc) - - - - - -

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 last tested: 2026-04-24

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