Installation

As tool

tox is a CLI tool that needs a Python interpreter (version 3.10 or higher) to run. We recommend either pipx or uv to install tox into an isolated environment. This has the added benefit that later you’ll be able to upgrade tox without affecting other parts of the system. We provide method for pip too here but we discourage that path if you can:

# install uv per https://docs.astral.sh/uv/#getting-started
uv tool install tox
tox --help

python -m pip install pipx-in-pipx --user
pipx install tox
tox --help

python -m pip install --user tox
python -m tox --help

You can install it within the global Python interpreter itself (perhaps as a user package via the --user flag). Be cautious if you are using a Python installation that is managed by your operating system or another package manager. pip might not coordinate with those tools, and may leave your system in an inconsistent state.

Requirements:

  • wheel (default): Installing tox via a wheel requires pip that understands the python-requires tag (see PEP 503). With pip this is version 9.0.0 or later (released November 2016). If installing from a mirror, ensure it forwards the python-requires tag (notably OpenStack mirrors don’t, and older devpi/devpi versions before 4.7.0 don’t).

  • sdist: When installing via a source distribution you need pip that handles PEP 517. With pip this is version 18.0.0 or later (released July 2018). If you cannot upgrade pip, ensure the build requirements from pyproject.toml are satisfied before installation.

latest unreleased

Installing an unreleased version is discouraged and should be only done for testing purposes:

uv tool install --from git+https://github.com/tox-dev/tox.git@main tox

pipx install git+https://github.com/tox-dev/tox.git@main

pip install git+https://github.com/tox-dev/tox.git@main

Requires pip version 18.0.0 or later.

For Python version compatibility, see System requirements.

Man Page Support

tox ships a compiled man page in its wheel. When installing tox:

  • System-wide (sudo pip install tox): Installs to /usr/share/man/man1/tox.1 automatically

  • User install (pip install --user tox): Installs to ~/.local/share/man/man1/tox.1 automatically

  • Package managers (apt, brew, dnf): Install to the appropriate system location

For user installs, ensure ~/.local/share/man is in your MANPATH:

# Add to ~/.bashrc or ~/.zshrc
export MANPATH="$HOME/.local/share/man:$MANPATH"

After updating your profile, restart your shell or run source ~/.bashrc.

Virtual Environment Installations

When tox is installed in a virtual environment (via pipx, uv tool, or venv), the man page is installed but not on the system MANPATH. Use the tox man command to set it up:

tox man

Building from Source

Package maintainers building from source can generate the man page using Sphinx:

tox run -e docs

# Man page is generated at .tox/docs_out/man/tox.1
install -D -m 644 .tox/docs_out/man/tox.1 /usr/share/man/man1/tox.1
gzip -9 /usr/share/man/man1/tox.1

After installation, view with man tox.