tox: tox.ini, Environments & Commands

tox automates testing across multiple isolated Python environments -- creating a clean virtualenv per configuration, installing dependencies, building/installing the project itself, and running commands in each. Commonly used to verify a library actually works across every Python version it claims to support.

Basic tox.ini

[tox]
envlist = py39, py310, py311, py312, lint

# [testenv] defines defaults shared by every environment in envlist
# that doesn't override it with its own [testenv:<name>] section
[testenv]
deps =
    pytest
    pytest-cov
commands = pytest --cov=mypackage tests/

# Named environment overriding the defaults -- doesn't need the
# project itself installed to just run a linter
[testenv:lint]
skip_install = true
deps = ruff
commands = ruff check .

[testenv:docs]
deps = sphinx
commands = sphinx-build -b html docs docs/_build

Running tox

# Runs every environment in envlist
tox

# Just one environment -- fast iteration while debugging a specific
# Python version's failure
tox -e py311

# Multiple specific environments
tox -e py311,lint

# Run the full matrix concurrently instead of sequentially
tox --parallel
# or: tox -p

What Each Environment Actually Does

• Creates a clean virtualenv for that environment (delegating to virtualenv/venv -- tox is the orchestration layer, not a reimplementation of environment isolation).

• Installs everything in deps (pytest, linters, etc. -- tools beyond the project's own runtime dependencies).

• By default, builds and installs the project package itself -- tests exercise the real installable package, not loose source files on a path.

• Runs commands inside that fully set-up environment.

• A dependency incompatible with one Python version fails that environment's setup -- surfacing a real compatibility problem instead of hiding it.