tox

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.

Install

• pip install tox Install tox

Quickstart

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.")