tox-uv: uv backend for tox

by Tim Hopper

tox-uv is a plugin for tox that replaces pip and virtualenv with uv. When installed alongside tox, it activates automatically and handles all virtual environment creation and dependency installation using uv’s resolver and installer. No changes to tox.ini are required for basic usage.

Installation

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

uv tool install tox --with tox-uv

Two distribution packages exist:

tox-uv bundles a uv binary alongside the plugin. This is the default and works without uv on the system PATH.
tox-uv-bare contains only the plugin. Use this in containers or CI environments where uv is already installed to avoid a duplicate binary.

Requirements

tox 4.40 or later (tox-uv does not support tox 3)
Python 3.10 or later

How it works

tox-uv registers replacement environment types that tox uses instead of its built-in virtualenv and pip backends:

Environment type	Purpose
`uv-venv-runner`	Default runner for test environments (replaces virtualenv + pip)
`uv-venv-lock-runner`	Runner that installs from a `uv.lock` file instead of `deps`
`uv-venv-pep-517`	PEP 517 packaging environment
`uv-venv-cmd-builder`	External command builder

The uv-venv-runner activates automatically for all environments. The lock runner must be enabled explicitly per environment with runner = uv-venv-lock-runner.

Configuration

tox-uv adds several per-environment settings to tox.ini:

Setting	Description	Default
`uv_resolution`	Dependency resolution strategy: `highest`, `lowest`, or `lowest-direct`	`highest`
`uv_python_preference`	How uv selects the Python interpreter (maps to uv’s `python-preference`)	uv default
`uv_seed`	Inject pip, setuptools, and wheel into the venv	`false`
`uv_sync_flags`	Additional flags passed to `uv sync` (lock runner only)	none
`uv_sync_locked`	Pass `--locked` to `uv sync` (lock runner only)	`true`
`dependency_groups`	PEP 735 groups to install in addition to the project	none
`only_groups`	PEP 735 groups to install instead of the project	none

Example: test against lowest supported dependencies

[testenv]
uv_resolution = lowest
deps =
    pytest
commands =
    pytest {posargs}

Example: use a lockfile

[testenv:locked]
runner = uv-venv-lock-runner
commands =
    pytest {posargs}

When using the lock runner, all dependencies come from uv.lock. The deps setting is ignored.

Environment variables

Variable	Purpose
`TOX_UV_PATH`	Override the path to the uv binary (takes precedence over bundled and system uv)

uv discovery order

TOX_UV_PATH environment variable
Bundled uv binary (when using the tox-uv package)
System uv on PATH (when using tox-uv-bare or if bundled is not found)

Python version discovery

tox-uv delegates Python discovery to uv. If a requested Python version (e.g. py312) is not installed on the system, uv downloads and installs it automatically. The uv_python_preference setting controls whether uv prefers system installations or managed downloads.

Falling back to pip

To bypass tox-uv for a single run (useful for debugging uv-specific issues):

tox --runner virtualenv r -e py313

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

Learn More

Also Mentioned In

Was this helpful?

Get Python tooling updates

Subscribe to the newsletter

Last updated on March 28, 2026

tox Twine

Please submit corrections and feedback...