tox-uv

tox-uv is a tox plugin, which replaces virtualenv and pip with uv in your tox environments. Note that you will get both the benefits (performance) or downsides (bugs) of uv.

• How to use
  • Installation options
  • uv discovery
• tox environment types provided
• PEP 723 inline script metadata
• uv.lock support
  • package
  • extras
  • no_default_groups
  • dependency_groups
  • only_groups
  • uv_sync_flags
  • uv_sync_locked
  • External package support
• Environment creation
  • uv_seed
  • uv_python_preference
• Package installation
• uv_resolution

How to use

Install tox-uv into the environment of your tox, and it will replace virtualenv and pip for all runs:

uv tool install tox --with tox-uv # use uv to install
tox --version # validate you are using the installed tox
tox r -e py312 # will use uv
tox --runner virtualenv r -e py312 # will use virtualenv+pip

Installation options

tox-uv is distributed as two packages:

• tox-uv (recommended): Meta package that includes both the plugin and a bundled uv binary. This ensures uv is always available and provides the best out-of-box experience.

• tox-uv-bare: Plugin-only package without the bundled uv binary. Use this in containerized environments (Docker, Kubernetes) where uv is pre-installed in the system to avoid downloading duplicate binaries.

Example Docker usage with tox-uv-bare:

FROM python:3.12
RUN pip install uv tox tox-uv-bare
# uv is already in the container, no need to bundle it again

uv discovery

tox-uv discovers the uv binary in the following order:

1. TOX_UV_PATH environment variable: Explicitly specify the uv binary location. Useful for testing custom uv builds or when uv is installed in a non-standard location.

   export TOX_UV_PATH=/custom/path/to/uv
   tox r
   

2. Bundled uv (when using tox-uv meta package): Uses the uv binary included with the tox-uv package.

3. System uv (when using tox-uv-bare or if bundled uv not found): Searches for uv in your system PATH.

If uv cannot be found, tox-uv will raise an error with installation instructions.

tox environment types provided

This package will provide the following new tox environments:

• uv-venv-runner is the ID for the tox environments runner for environments not using a lock file.
• uv-venv-lock-runner is the ID for the tox environments runner for environments using uv.lock (note we can’t detect the presence of the uv.lock file to enable this because that would break environments not using the lock file - such as your linter).
• uv-venv-pep-723 is the ID for the PEP 723 inline script metadata runner. When tox-uv is installed, virtualenv-pep-723 is also transparently backed by uv.
• uv-venv-pep-517 is the ID for the PEP-517 packaging environment.
• uv-venv-cmd-builder is the ID for the external cmd builder.

PEP 723 inline script metadata

PEP 723 lets Python scripts declare their dependencies and required Python version inline via comment blocks.

Given a script tools/check.py:

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests>=2.31", "rich"]
# ///

import requests
from rich import print

print(requests.get("https://httpbin.org/get").json())

Configure tox to run it:

[testenv:check]
runner = virtualenv-pep-723
script = tools/check.py

When tox-uv is installed, virtualenv-pep-723 is transparently backed by uv. You can also use runner = uv-venv-pep-723 to explicitly request the uv-backed runner regardless of plugin installation.

To disable the automatic promotion and use tox's built-in virtualenv+pip implementation, set TOX_UV_NO_PEP723=1.

Run with tox r -e check. Positional arguments are forwarded: tox r -e check -- --verbose.

To override the default command (which runs the script), set commands as usual:

[testenv:check]
runner = virtualenv-pep-723
script = tools/check.py
commands = python -m pytest tests/

uv.lock support

If you want for a tox environment to use uv sync with a uv.lock file you need to change for that tox environment the runner to uv-venv-lock-runner. Furthermore, should in such environments you use the extras config to instruct uv to install the specified extras, for example (this example is for the tox.ini, for other formats see the documentation here):

[testenv:fix]
description = run code formatter and linter (auto-fix)
skip_install = true
deps =
    pre-commit-uv>=4.1.1
commands =
    pre-commit run --all-files --show-diff-on-failure

[testenv:type]
runner = uv-venv-lock-runner
description = run type checker via mypy
commands =
    mypy {posargs:src}

[testenv:dev]
runner = uv-venv-lock-runner
description = dev environment
extras =
    dev
    test
    type
commands =
    uv pip tree

In this example:

• fix will use the uv-venv-runner and use uv pip install to install dependencies to the environment.
• type will use the uv-venv-lock-runner and use uv sync to install dependencies to the environment without any extra group.
• dev will use the uv-venv-lock-runner and use uv sync to install dependencies to the environment with the dev, test and type extra groups.

Note that when using uv-venv-lock-runner, all dependencies will come from the lock file, controlled by extras. Therefore, options like deps are ignored (and all others enumerated here as Python run flags).

package

How to install the source tree package, must be one of:

• skip - do not install the project,
• wheel - install the project as a non-editable wheel,
• editable (default) - install the project in editable mode,
• uv - with uv-venv-runner uses uv directly to install the project (bypassing tox's PEP-517 packaging), with uv-venv-lock-runner behaves like wheel,
• uv-editable - with uv-venv-runner uses uv directly to install in editable mode (bypassing tox's PEP-517 packaging), with uv-venv-lock-runner behaves like editable.

With uv-venv-runner, prefer uv/uv-editable when you need non-standard features of uv, such as tool.uv.sources. With uv-venv-lock-runner, uv sync already handles installation natively so all modes work through it.

extras

A list of string that selects, which extra groups you want to install with uv sync. By default, it is empty.

no_default_groups

A boolean flag to toggle installation of the uv default development groups. By default, it will be true if the dependency_groups is not empty and false otherwise.

dependency_groups

Specify PEP 735 – Dependency Groups to install in addition to the project and its dependencies (maps to uv sync --group). For example, dependency_groups = ["test", "docs"] installs the project, its default dependencies, and the test and docs groups.

only_groups

Install only these PEP 735 – Dependency Groups, excluding the project and all other dependencies (maps to uv sync --only-group). Use this when you need a dependency group in complete isolation, such as CI tooling from a private index. For example, only_groups = ["ci"] installs only the ci group without the project or any of its dependencies.

Key difference: dependency_groups adds groups to the standard install, while only_groups replaces the entire install with just those groups.

uv_sync_flags

A list of strings, containing additional flags to pass to uv sync (useful because some flags are not configurable via environment variables). For example, if you want to install the package in non editable mode and keep extra packages installed into the environment you can do:

uv_sync_flags = --no-editable, --inexact

If --frozen is included in uv_sync_flags, tox-uv will automatically suppress the implicit --locked argument since the two flags are mutually exclusive in uv:

uv_sync_flags = --frozen

uv_sync_locked

By default tox-uv will call uv sync with --locked argument, which is incompatible with other arguments like --prerelease or --upgrade that you might want to add to uv_sync_flags for some test scenarios. You can set this to false to avoid such conflicts.

If the UV_FROZEN environment variable is set to a truthy value, tox-uv will automatically suppress --locked and pass --frozen to uv sync instead. This is useful in CI environments where the lockfile was created on a different platform and platform-specific metadata validation should be skipped:

UV_FROZEN=1 tox

External package support

Should tox be invoked with the --installpkg flag (the argument must be either a wheel or source distribution) the sync operation will run with --no-install-project and uv pip install will be used afterward to install the provided package.

Environment creation

We use uv venv to create virtual environments. This process can be configured with the following options:

uv_seed

This flag, set on a tox environment level, controls if the created virtual environment injects pip, setuptools and wheel into the created virtual environment or not. By default, it is off. You will need to set this if you have a project that uses the old legacy-editable mode, or your project doesn’t support the pyproject.toml powered isolated build model.

uv_python_preference

This flag, set on a tox environment level, controls how uv select the Python interpreter.

By default, uv will attempt to use Python versions found on the system and only download managed interpreters when necessary. However, It is possible to adjust uv's Python version selection preference with the python-preference option.

system_site_packages (sitepackages)

Create virtual environments that also have access to globally installed packages. Note the default value may be overwritten by the VIRTUALENV_SYSTEM_SITE_PACKAGES environment variable. This flag works the same way as the one from tox native virtualenv implementation.

Package installation

We use uv pip to install packages into the virtual environment. The behavior of this can be configured via the following options:

uv_resolution

This flag, set on a tox environment level, informs uv of the desired resolution strategy:

• highest - (default) selects the highest version of a package satisfying the constraints.
• lowest - install the lowest compatible versions for all dependencies, both direct and transitive.
• lowest-direct - opt for the lowest compatible versions for all direct dependencies, while using the latest compatible versions for all transitive dependencies.

This is an uv specific feature that may be used as an alternative to frozen constraints for test environments if the intention is to validate the lower bounds of your dependencies during test executions.

Note: When using uv_resolution with dependency_groups, all dependencies from both deps and dependency_groups are combined into a single install operation. This ensures the resolution strategy applies correctly across all requirements, preventing sequential installations from resolving transitive dependencies before the strategy can apply to overlapping direct dependencies.

Cache invalidation for UV_* environment variables

tox-uv includes a curated set of UV_* environment variables in the install cache key. When any of these variables change via set_env, the cached environment is invalidated and packages are reinstalled so that uv can re-resolve with the new settings. The tracked variables are:

UV_CONSTRAINT, UV_DEFAULT_INDEX, UV_EXCLUDE, UV_EXCLUDE_NEWER, UV_EXTRA_INDEX_URL, UV_FIND_LINKS, UV_FORK_STRATEGY, UV_INDEX, UV_INDEX_STRATEGY, UV_INDEX_URL, UV_KEYRING_PROVIDER, UV_NO_INDEX, UV_NO_SOURCES, UV_OFFLINE, UV_OVERRIDE, UV_PRERELEASE, UV_REQUIRE_HASHES, UV_RESOLUTION, UV_TORCH_BACKEND.

Variables that do not affect resolution (e.g. UV_CONCURRENT_DOWNLOADS, UV_NO_PROGRESS, UV_CACHE_DIR) are not tracked and changing them will not trigger a reinstall.