pytest-env

library1.7.0pypypi✓ verified 27d ago

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.

testing

pip install pytest-env

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-ENV

pytest-env

testingpythonv1.7.0

Install

2.7s avg

Import

—

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.7.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 31.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.7s · import 0.000s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

Debug

Known issues

breakingPython 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.

affects: <1.2.0 (for Python 3.9 users)

gotchaConfiguration 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.

affects: All versions

gotchaBehavior 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.

affects: >=1.4.0

gotchaEnvironment 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`.

affects: <1.6.0 (for default overwrite behavior), All versions (for explicit control)

gotchaUnsetting 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.

affects: <1.3.0 (feature not available)

gotchaWhen 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.

affects: All versions

gotchaConfiguration 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.

affects: All versions

Upgrade

Version history

1.7.0latest on PyPI · released Jul 21, 2026

Audit

Dependencies

pytestrequiredCore testing framework, pytest-env is a plugin for it.

python-dotenvrequiredUsed for parsing .env files for environment variables.

tomlioptionalRequired for TOML parsing on Python versions prior to 3.11.

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/pytest-dev/pytest-env ↗

packagehttps://pypi.org/project/pytest-env/ ↗