{"id":1051,"library":"pytest-env","title":"pytest-env","description":"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.","status":"active","version":"1.6.0","language":"python","source_language":"en","source_url":"https://github.com/pytest-dev/pytest-env","tags":["pytest","testing","environment variables","plugins","configuration"],"install":[{"cmd":"pip install pytest-env","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core testing framework, pytest-env is a plugin for it.","package":"pytest","optional":false},{"reason":"Used for parsing .env files for environment variables.","package":"python-dotenv","optional":false},{"reason":"Required for TOML parsing on Python versions prior to 3.11.","package":"tomli","optional":true}],"imports":[{"note":"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.","symbol":"pytest-env plugin","correct":"Functionality is automatically loaded by pytest via entry points."}],"quickstart":{"code":"# pyproject.toml\n[tool.pytest_env]\nDATABASE_URL = \"postgresql://localhost/test_db\"\nDEBUG = \"true\"\nMY_API_KEY = \"${MY_API_KEY:-default_key}\"\n\n# tests/test_my_app.py\nimport os\n\ndef test_database_connection():\n    assert os.environ[\"DATABASE_URL\"] == \"postgresql://localhost/test_db\"\n    assert os.environ[\"DEBUG\"] == \"true\"\n\ndef test_api_key():\n    # MY_API_KEY will be expanded using existing env var or default_key\n    assert \"MY_API_KEY\" in os.environ\n    print(f\"API Key: {os.environ['MY_API_KEY']}\")\n\n# Run from your terminal:\n# pytest\n# To see verbose output of env var assignments:\n# pytest --pytest-env-verbose","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.10 or newer.","message":"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.","severity":"breaking","affected_versions":"<1.2.0 (for Python 3.9 users)"},{"fix":"Be mindful of the configuration file hierarchy and how inline variables override `.env` file contents. Use `--pytest-env-verbose` for debugging source attribution.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly choose between override (`PATH`) and extend (`+PATH`) modes based on desired behavior. Ensure that any file specified via `--envfile` exists.","message":"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.","severity":"gotcha","affected_versions":">=1.4.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<1.6.0 (for default overwrite behavior), All versions (for explicit control)"},{"fix":"Upgrade to `pytest-env` 1.3.0 or newer to use the unsetting functionality.","message":"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.","severity":"gotcha","affected_versions":"<1.3.0 (feature not available)"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T23:09:15.178Z","next_check":"2026-06-29T00:00:00.000Z","problems":[{"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`.","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.","error":"PytestUnknownConfigurationWarning: Unknown config option: env"},{"fix":"Use `pytest --env-var KEY=VALUE` to set environment variables from the command line.","cause":"The command-line option for setting environment variables with `pytest-env` is `--env-var`, not `--env`.","error":"ERROR: unknown option: --env"},{"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\"`.","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.","error":"ValueError: Invalid configuration line for env: 'KEY:VALUE'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.6.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","installed_version":"1.1.5","pypi_latest":"1.6.0","is_stale":true,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"30.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":2.7,"import_time_s":null,"mem_mb":null,"disk_size":"31M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"33.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":2.6,"import_time_s":null,"mem_mb":null,"disk_size":"34M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"25.4M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":2.6,"import_time_s":null,"mem_mb":null,"disk_size":"26M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"25.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":2.5,"import_time_s":null,"mem_mb":null,"disk_size":"26M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"30.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3,"import_time_s":null,"mem_mb":null,"disk_size":"30M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pytest-env","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}