tox-uv

1.34.0 · active · verified Thu Apr 09

tox-uv is a plugin that integrates uv, the fast Python package installer and resolver, with tox, the standard virtual environment management and test automation tool. It provides a drop-in replacement for tox's default virtual environment creation and dependency management, leveraging uv for significantly faster operations. The current version is 1.34.0, and it follows an active release cadence with frequent updates.

Warnings

breaking Starting with tox-uv 1.32.0, the project adopted a monorepo structure, differentiating between a `bare` and `meta` package. While `tox-uv` (the meta-package) remains the primary installation, be aware of this refactoring if you're dealing with advanced plugin development or specific `uv` integration scenarios.
Fix: Ensure you are installing `tox-uv` (the meta-package) which bundles `uv` and provides the full integration. Most users will not need to change anything unless they were trying to build from source or use a more granular package.
gotcha tox-uv explicitly requires Python 3.10 or newer. Attempting to use it with older Python versions will result in installation failures or runtime errors.
Fix: Ensure your base Python environment (where `tox` and `tox-uv` are installed) is Python 3.10 or higher. The test environments managed by tox can still target older Python versions if supported by `uv` and your system.
gotcha To ensure tox uses uv for dependency resolution and installation, `tox-uv` must be specified in the `requires` section of your tox configuration. If omitted, tox will fallback to its default package installer (typically pip).
Fix: Always include `requires = tox-uv` (or `requires = ["tox-uv"]` in `pyproject.toml`) in your `[tox]` section to activate the plugin.
gotcha Certain behaviors of `uv` within tox can be controlled via `uv_resolution` settings (e.g., `uv_resolution = eager` or `uv_resolution = resolve_and_install`). Misconfiguration here can lead to unexpected dependency outcomes.
Fix: Consult the `tox-uv` documentation for available `uv_resolution` options and their effects. Start with the default behavior and only adjust if you have specific needs for dependency resolution strategy.

Install

pip install tox-uv Install tox-uv

Imports

tox-uv activation

tox-uv is a tox plugin; it's activated by adding `requires = tox-uv` to your `tox.ini` or `pyproject.toml` configuration under the `[tox]` section. There are no direct Python `import` statements for `tox-uv` in user code.

tox-uv extends tox functionality and is not directly imported into Python scripts.

Quickstart

To use tox-uv, first install it. Then, configure your `pyproject.toml` (recommended for tox 4+) or `tox.ini` to declare `tox-uv` as a required plugin. tox will automatically detect and use `uv` for virtual environment creation and dependency management for all defined test environments.

# pyproject.toml
[tool.tox]
min_version = "4.0"
requires = ["tox-uv"]
env_list = ["py311", "py312"]

[testenv]
package = "skip"
deps = ["pytest"]
commands = ["pytest"]

# Or for a simple tox.ini:
# [tox]
# min_version = 4.0
# requires = tox-uv
# env_list = py

# [testenv:py]
# deps = pytest
# commands = pytest

view raw JSON →