tox

Run all test environments

$ tox

$ tox -e [py39]

$ tox -e [py38,py39,lint]

$ tox -l

$ tox -r

$ tox -p

$ tox -- [--verbose]

$ tox -r -e [py39]

tox [-e envs] [-r] [-p] [-l] [options] [-- testargs_]

tox automates testing Python packages across multiple Python versions and environments. It creates isolated virtualenvs, installs packages, and runs tests.
Configuration in tox.ini or pyproject.toml defines environments. Each environment specifies: Python version, dependencies, and commands to run. Common setups test multiple Python versions (py38, py39, py310) plus linting environments.
Environment creation installs the package in development mode plus test dependencies. This catches installation issues early. Recreate mode (-r) rebuilds environments from scratch.
Parallel mode (-p) runs environments simultaneously, speeding up multi-version testing on machines with multiple cores. Output is collected and displayed after completion.
Beyond testing, tox runs any command: linting (flake8, mypy), documentation builds (sphinx), formatting checks. Multiple commands chain in sequence.
The double-dash (--) passes arguments to the test command, enabling pytest flags or test selection without modifying tox.ini.

-e ENVLIST, --envlist ENVLIST

Environments to run.

Recreate virtual environments.

Run environments in parallel.

List environments.

List all environments including generated.

Create development environment.

Configuration file path.

Skip environments without interpreter.

Verbose output.

Quiet output.

Install but don't test.

Only create source distribution.

Write results as JSON.

Pass remaining args to test command.

Python versions must be installed for their environments. Initial environment creation downloads dependencies. Parallel mode may hit resource limits. Complex configurations can be hard to debug. Some CI systems prefer simpler approaches.

tox was created by Holger Krekel (creator of pytest) around 2010 to solve multi-Python testing. It became the standard tool for Python package testing, used by major projects. Version 4 (2022) brought significant improvements and pyproject.toml support.

pytest(1), nox(1), virtualenv(1), hatch(1)