tox: Test Across Environments Command Reference

Automate testing across multiple Python versions and configs.

tox creates isolated environments defined in tox.ini (or pyproject.toml) and runs your test commands in each. It standardizes "works across Pythons" testing for CI and local runs.

Common flags / usage

tox -- run every default environment
-e py311,py312 -- run specific environments
-p, --parallel -- run environments in parallel
-r, --recreate -- rebuild environments from scratch
-- ARGS -- pass extra args through to the test command

Example

shell

strategy:
  matrix:
    python: ['3.11', '3.12']
steps:
  - uses: actions/setup-python@v5
    with:
      python-version: ${{ matrix.python }}
  - run: pip install tox
  - run: tox -e py${{ matrix.python }}

In CI

You can let tox iterate all Python versions on one runner, or map each version to a matrix leg (shown above) so legs run in parallel across managed runners. Cache the tox work directory and the pip cache to speed environment rebuilds.

Key takeaways

tox runs your tests in isolated, declaratively defined environments.
-e selects environments; -p runs them in parallel.
Map tox envs to a CI matrix to parallelize across runners.