tox Cheat Sheet

Overview

tox is a command-line tool for automating Python testing across multiple environments. It creates isolated virtual environments, installs dependencies, and runs test commands for each configured environment. tox is commonly used to verify that packages work across different Python versions and dependency combinations before publishing.

tox 4.x uses tox.ini or pyproject.toml for configuration and supports parallel execution, conditional environments, dependency pinning, and integration with CI/CD systems. It replaces manual virtual environment management with declarative configuration.

Installation

pip install tox
# or
pipx install tox

# Verify
tox --version

Core Commands

Command	Description
`tox`	Run all default environments
`tox -e py312`	Run specific environment
`tox -e py310,py311,py312`	Run multiple environments
`tox -p`	Run environments in parallel
`tox -l`	List configured environments
`tox --listenvs-all`	List all environments
`tox -r`	Recreate environments
`tox -e lint`	Run lint environment
`tox --devenv venv`	Create dev environment
`tox config`	Show resolved configuration

Configuration

tox.ini

[tox]
env_list = py310, py311, py312, lint, typecheck
min_version = 4.0

[testenv]
deps =
    pytest>=7.0
    pytest-cov
    -r requirements.txt
commands =
    pytest {posargs:tests/}

[testenv:lint]
deps = ruff
commands = ruff check src/ tests/

[testenv:typecheck]
deps =
    mypy
    types-requests
commands = mypy src/

[testenv:docs]
deps =
    mkdocs
    mkdocs-material
commands = mkdocs build

pyproject.toml

[tool.tox]
env_list = ["py310", "py311", "py312", "lint"]
min_version = "4.0"

[tool.tox.env_run_base]
deps = ["pytest>=7.0", "pytest-cov"]
commands = [["pytest", "{posargs:tests/}"]]

[tool.tox.env.lint]
deps = ["ruff"]
commands = [["ruff", "check", "src/", "tests/"]]

Environment Variables and Settings

[testenv]
deps = pytest
set_env =
    PYTHONPATH = {toxinidir}/src
    DATABASE_URL = sqlite:///test.db
    CI = true
pass_env =
    HOME
    SSH_AUTH_SOCK
    AWS_*
commands = pytest {posargs}

Advanced Usage

Dependency Matrix

[tox]
env_list = py{310,311,312}-django{42,50}

[testenv]
deps =
    pytest
    django42: Django>=4.2,<4.3
    django50: Django>=5.0,<5.1
commands = pytest {posargs}

Parallel Execution

# Run all environments in parallel
tox -p auto

# Run with limited parallelism
tox -p 4

# Show live output
tox -p auto -o

Conditional Configuration

[testenv]
deps =
    pytest
    py310: importlib-metadata
platform =
    linux: linux
    macos: darwin
commands =
    python -m pytest {posargs}

Pre/Post Commands

[testenv]
deps = pytest
commands_pre =
    python -c "print('Setting up...')"
commands =
    pytest {posargs}
commands_post =
    python -c "print('Cleaning up...')"

Factor-Based Config

[testenv:coverage-{py310,py311,py312}]
deps =
    pytest
    pytest-cov
commands =
    pytest --cov=src --cov-report=xml {posargs}

Troubleshooting

Issue	Solution
Python version not found	Install the Python version; check `python3.x` is in PATH
Dependency install fails	Use `-r` to recreate env; check constraints
Tests pass locally but fail in tox	Check `set_env` and `pass_env` settings
Slow environment creation	Use `--skip-missing-interpreters` in CI
Package install fails	Verify `pyproject.toml` build config

# Recreate all environments
tox -r

# Show environment config
tox config -e py312

# Pass arguments to pytest
tox -- -x -v tests/test_specific.py

# Skip missing interpreters
tox --skip-missing-interpreters

# Verbose output
tox -v