{"id":2318,"library":"tox-uv","title":"tox-uv","description":"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.","status":"active","version":"1.34.0","language":"en","source_language":"en","source_url":"https://github.com/tox-dev/tox-uv","tags":["tox","uv","virtual environment","package manager","build tool","testing","automation"],"install":[{"cmd":"pip install tox-uv","lang":"bash","label":"Install tox-uv"}],"dependencies":[{"reason":"tox-uv is a plugin for tox and requires tox version 4.0 or newer to function.","package":"tox","optional":false},{"reason":"uv is the core package manager leveraged by this plugin; it is bundled with tox-uv.","package":"uv","optional":true}],"imports":[{"note":"tox-uv extends tox functionality and is not directly imported into Python scripts.","symbol":"tox-uv activation","correct":"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."}],"quickstart":{"code":"# pyproject.toml\n[tool.tox]\nmin_version = \"4.0\"\nrequires = [\"tox-uv\"]\nenv_list = [\"py311\", \"py312\"]\n\n[testenv]\npackage = \"skip\"\ndeps = [\"pytest\"]\ncommands = [\"pytest\"]\n\n# Or for a simple tox.ini:\n# [tox]\n# min_version = 4.0\n# requires = tox-uv\n# env_list = py\n\n# [testenv:py]\n# deps = pytest\n# commands = pytest","lang":"toml","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.32.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0 (initial versions) through current"},{"fix":"Always include `requires = tox-uv` (or `requires = [\"tox-uv\"]` in `pyproject.toml`) in your `[tox]` section to activate the plugin.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions supporting `uv_resolution` (introduced early)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}