tox

4.51.0 verified Sat Apr 11 auth: no python

tox is a generic virtual environment management and test command-line tool for Python projects. It automates and standardizes testing across various Python versions, interpreters, and dependency configurations, serving as a powerful frontend for local development and Continuous Integration servers. Currently at version 4.51.0, tox maintains an active development pace with frequent patch and minor releases, often on a monthly or bi-weekly cadence.

pip install tox

Common errors

error command not found: tox ↓

cause The 'tox' executable is not in your system's PATH, typically because it wasn't installed globally or the virtual environment it was installed into isn't activated.

fix

Install tox using pip install tox in your global environment or a project-specific virtual environment, and ensure that virtual environment is activated if applicable.

error ModuleNotFoundError: No module named 'pytest' ↓

cause A Python package required by your tests or application is missing from the `deps` list in your `tox.ini` file for the specific `testenv` where the error occurs.

fix

Add the missing package to the deps list in the relevant [[testenv]] section of your tox.ini. For example: deps = pytest

error ERROR: InterpreterNotFound: python3.9 ↓

cause The specified Python interpreter version (e.g., `python3.9`) is not installed on your system or is not discoverable in the system's PATH.

fix

Install the required Python version on your system. If it's installed but not found, ensure it's in your system's PATH, or configure base_python = /path/to/python3.9 in the [[testenv]] section of tox.ini.

error ERROR: ConfigError: The 'commands' key is required in section 'testenv:py39'. ↓

cause Your `tox.ini` configuration is missing a mandatory key like `commands` within a `[[testenv]]` section, or there's a syntax error preventing tox from parsing the configuration correctly.

fix

Review your tox.ini file, ensuring all required keys are present and correctly formatted according to tox v4 configuration (e.g., commands = python -m pytest).

error ERROR: tox.ini file not found. ↓

cause Tox was executed in a directory that does not contain a `tox.ini` or `pyproject.toml` file with tox configuration, or the file is named incorrectly.

fix

Run tox from the root directory of your project where tox.ini is located, or specify the path to your config file using tox -c path/to/tox.ini.

Warnings

breaking Upgrading from tox 3 to tox 4 involves significant breaking changes due to a ground-up rewrite. Key changes include the CLI command structure (e.g., `tox run -e` instead of `tox -e`), stricter INI parsing rules (e.g., `#` is always a comment, `pass_env` requires comma/newline separators), removal of `-U` in `deps`, and a completely new plugin API. Environment names matching new `tox 4` subcommands can also lead to ambiguity. ↓

fix Consult the 'Upgrading to tox v4' documentation for a comprehensive guide. Update CLI commands, adjust INI configuration files to new parsing rules (e.g., escape literal `#` with `\#`, use `,` for `pass_env`), and rewrite any custom plugins to the new API.

gotcha tox environments are often reused for performance. However, tox does not always detect changes in `setup.py` or `requirements.txt` files that define package dependencies. This can lead to stale virtual environments where tests run against outdated dependencies. ↓

fix Always explicitly recreate environments by running `tox -r` or `tox run -r` when you suspect dependency changes, or when encountering unexpected test failures due to environment state.

gotcha By design, tox environments are isolated and do not inherit host system environment variables unless explicitly configured. This can cause commands to fail if they rely on external environment variables (e.g., API keys, build flags) that are not passed through. ↓

fix Use the `pass_env` setting in your `tox.ini` or `pyproject.toml` to explicitly list environment variables that should be passed from the host to the tox environment. Wildcards (`*`) can be used for patterns.

gotcha tox supports multiple configuration files (`pyproject.toml` (native TOML), `tox.toml`, `pyproject.toml` (legacy INI via `legacy_tox_ini`), `tox.ini`, `setup.cfg`) with a specific precedence order. Mixing configuration styles or placing core settings in environment-specific sections can lead to ignored or unexpected behavior. TOML is the recommended format for new projects as of tox 4, offering more robustness, but INI remains supported. ↓

fix Consistently use one configuration format (preferably native `pyproject.toml` for new projects). Always place core settings in the global `[tox]` section (INI) or `[tool.tox]` table (TOML), and environment-specific settings within their respective `[testenv]` or `[tool.tox.env.<name>]` sections. Use `tox config` or `tox run -v` to inspect the resolved configuration and identify misplaced keys.

gotcha When `pip` executes inside a tox environment, it may issue warnings regarding running as the 'root' user, which can lead to permission issues, or display notices about available `pip` updates. These are `pip` specific advisories and not directly indicative of a `tox` failure or misconfiguration. ↓

fix To address 'root' warnings, ensure `tox` is run as a non-root user. If running in a container as root is unavoidable, be aware of potential permission conflicts. Pip update notices can be ignored if not critical, or suppressed by setting `PIP_DISABLE_PIP_VERSION_CHECK=1` in `pass_env` (e.g., `pass_env = PIP_DISABLE_PIP_VERSION_CHECK`). Updating pip within a tox env is generally not recommended as dependency versions should be fixed.

gotcha pip warns about running as the 'root' user, which can lead to permission issues and conflicts with system package managers. Additionally, pip provides notices about new available versions. ↓

fix To address the 'root' user warning, always run pip within a virtual environment. If running in a container, ensure that applications are run as a non-root user. For pip update notices, consider updating pip by running `pip install --upgrade pip` (preferably within a virtual environment).

Quickstart last tested: 2026-04-24

This quickstart sets up a basic Python project with a `pyproject.toml` file configured for `tox`. It defines two environments: `py` (to run pytest) and `lint` (to run ruff). After running this Python script, navigate to the directory where it created the `pyproject.toml` and `my_package` folder, then simply execute `tox` in your terminal. tox will automatically create isolated virtual environments, install dependencies, and run the specified commands.

import os

# Create a dummy project structure
os.makedirs('my_package/tests', exist_ok=True)
with open('my_package/main.py', 'w') as f:
    f.write('def add(a, b):\n    return a + b')
with open('my_package/tests/test_main.py', 'w') as f:
    f.write('from my_package.main import add\n\ndef test_add():\n    assert add(1, 2) == 3')

# Create pyproject.toml for tox configuration
with open('pyproject.toml', 'w') as f:
    f.write('''
[project]
name = "my_package"
version = "0.1.0"

[tool.tox]
env_list = ["py", "lint"]

[tool.tox.env_run_base]
description = "Run the test suite with pytest"
deps = ["pytest>=8"]
commands = ["pytest {posargs:tests}"]

[tool.tox.env.lint]
description = "Run linters"
skip_install = true
deps = ["ruff"]
commands = ["ruff check {posargs:.}"]
''')

print("Project setup complete. Now run 'tox' in your terminal.")