Install & Compatibility
Where this runs
tested against v1.36.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 32.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.8s · import 0.000s · 33MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
tox --version
Debug
Known issues
breakingStarting 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.fixEnsure 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.
affects: >=1.32.0
gotchatox-uv explicitly requires Python 3.10 or newer. Attempting to use it with older Python versions will result in installation failures or runtime errors.fixEnsure 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.
affects: <1.0.0 (initial versions) through current
gotchaTo 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).fixAlways include `requires = tox-uv` (or `requires = ["tox-uv"]` in `pyproject.toml`) in your `[tox]` section to activate the plugin.
affects: All versions
gotchaCertain 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.fixConsult 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.
affects: All versions supporting `uv_resolution` (introduced early)
Upgrade
Version history
1.36.0latest on PyPI · released Jul 21, 2026
Audit
Dependencies
toxrequiredtox-uv is a plugin for tox and requires tox version 4.0 or newer to function.
uvoptionaluv is the core package manager leveraged by this plugin; it is bundled with tox-uv.