Tox Python Testing: Step-by-Step Guide

Tox automates Python project testing across multiple environments, so you can verify your code works with different Python versions and dependency sets without manual setup. This guide walks you through configuring tox, running it, and interpreting results. You’ll need a Python project with tests and a basic understanding of virtual environments.

What You’ll Need

Python 3.7 or newer installed on your system (tox itself runs on Python 3, but can test other versions if they’re installed).
A Python project with a pyproject.toml or setup.py file (tox reads metadata from these).
A test suite using pytest, unittest, or another framework—tox will run whatever command you specify.
Pip installed (usually comes with Python).

Step-by-Step

Install tox globally (or in a virtual environment) using pip: pip install tox. Verify with tox --version.
Create a tox configuration file named tox.ini in your project’s root directory. This file defines environments and commands.
Define the base configuration in tox.ini. Start with the [tox] section, specifying the environments you want to test. For example:
```
[tox]
envlist = py38, py39, py310, lint
```
This sets up three Python version environments plus a lint environment.
Configure each environment under its own section. For Python version environments, you only need to specify dependencies and test commands. Example:
```
[testenv]
commands = pytest
deps = pytest
```
This applies to all environments unless overridden.
Add a lint environment (optional but common). Use a separate section to run flake8 or black:
```
[testenv:lint]
commands = flake8 mypackage
deps = flake8
```
Specify package installation if needed. By default, tox installs your project in editable mode. If you need extra dependencies for building, add extras or deps in the environment section.
Run tox from the project root: tox. This creates virtual environments for each env in a .tox directory, installs dependencies, and runs the commands.
Watch the output. Tox prints a summary at the end showing which environments passed or failed. A green checkmark means success, a red X means failure.
Re-run after fixing issues. If a test fails, fix the code or test, then run tox again. Tox reuses existing environments unless you change configuration or dependencies.
Use tox with CI. In your continuous integration setup, simply run tox—it will execute all environments. You can also run specific environments with tox -e py39.

Common Mistakes

Not listing all Python versions you want to support. If you don’t include them in envlist, they won’t be tested.
Forgetting to install test dependencies. Your tests may rely on pytest, mock, or other packages—list them in deps.
Using system Python paths. Tox creates isolated environments; don’t rely on globally installed packages.
Ignoring the basepython setting. If you need a specific Python version, specify it with basepython = python3.9 in the environment section, especially when tox can’t find the interpreter.
Missing skip_install for lint environments. If you don’t want to install your package for linting, add skip_install = true.
Not cleaning up environments after major dependency changes. If your dependencies change significantly, run tox -r to recreate environments.

Tips

Use tox -l to list all available environments without running them.
Run a single environment with tox -e py39 to save time during development.
Pass extra arguments to the test command with tox -- --verbose (everything after -- goes to the command).
Use extras to install optional dependencies from your package: extras = dev.
Set usedevelop = true (default) to install your package in editable mode, which speeds up testing.
Add parallel_show_output = true in [tox] to see output from parallel runs.
Use tox.ini for both local and CI—it’s the single source of truth.

Troubleshooting

“Interpreter not found”: Tox can’t locate the Python version specified. Install that Python version or specify the full path in basepython.
“Command not found”: The command (e.g., pytest) isn’t installed in the environment. Add it to deps.
Tests fail only in tox but pass locally: Check for environment-specific issues like missing dependencies, different working directory, or environment variables. Use passenv to pass through needed variables.
Slow test runs: Use tox -p to run environments in parallel. Also, consider using --develop to avoid reinstalling your package.
Dependency conflicts: If your package requires specific versions, pin them in deps or use constraints files.
Changes to tox.ini not taking effect: Tox caches some settings; run tox -r to recreate environments.

Frequently Asked Questions

Can tox test multiple Python versions if only one is installed?

No, tox needs each Python interpreter installed on your system. You can install multiple versions via pyenv or your OS package manager.

How do I run tox with a specific environment variable?

Use passenv = MY_VAR in the [testenv] section to pass it from your shell. Alternatively, set it in the command: MY_VAR=value tox.

Can I use tox with Django or Flask projects?

Yes, just add the framework to deps and set up your test command. For Django, you might use python manage.py test.

What’s the difference between tox and virtualenv?

Virtualenv creates a single isolated environment; tox manages multiple environments and automates the process of creating, installing, and testing across them.

How do I skip an environment during a run?

Use tox -e py39 --notest to skip tests but set up the environment, or temporarily remove it from envlist.

Can I use tox with conda environments?

Yes, set basepython = /path/to/conda/env/bin/python or use the conda plugin, but it’s simpler to stick with standard Python environments.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →