How to use uv to speed up tox

tox spends most of its time creating virtual environments and installing dependencies. The tox-uv plugin replaces both pip and virtualenv with uv, cutting that overhead without changing how you write tox.ini or run your test matrix.

Install tox with tox-uv

The recommended approach installs tox and the plugin together as a uv tool:

uv tool install tox --with tox-uv

This gives you a tox command backed by uv. The plugin activates automatically; no changes to tox.ini are needed.

If you already have tox installed via pip:

pip install tox-uv

Verify it’s working

Run any tox environment and watch the output. You should see uv commands instead of pip:

tox -e py313

Look for lines like uv venv and uv pip install in the output. If you see virtualenv and pip install instead, the plugin is not active. Confirm it is installed in the same environment as tox:

tox --list-plugins

The output should include entries starting with tox-uv-bare.

Combine with parallel execution

tox can run environments concurrently. Pair this with tox-uv for the biggest speed gains on multi-version test matrices:

tox p

This runs all environments in envlist in parallel, each using uv for environment creation and dependency installation. On a project with four Python versions and a dozen test dependencies, this combination can reduce a full tox run from minutes to seconds.

To limit parallelism (useful in CI where resources are constrained):

tox p -o --parallel 2

Use uv’s Python downloads

tox-uv uses uv’s built-in Python discovery, which means uv can download Python versions on demand if they are not already installed on your system. A tox.ini like this works without pre-installing Python 3.11 or 3.12:

[tox]
envlist = py311,py312,py313

If tox cannot find Python 3.11 on the system, uv fetches and installs it automatically.

Control dependency resolution

tox-uv exposes uv’s resolution strategies through the uv_resolution setting. This is useful for testing against your lowest supported dependency versions:

[testenv]
uv_resolution = lowest

Valid values are highest (the default), lowest, and lowest-direct.

Fall back to pip for a single run

If you need to bypass tox-uv temporarily (to debug a uv-specific issue, for example), pass the --runner flag:

tox --runner virtualenv r -e py313

This runs the specified environment using the standard virtualenv and pip backend.

Learn more

• tox reference page
• uv reference page
• How to test against multiple Python versions using uv
• tox-uv reference page
• tox parallel mode documentation