{"id":20784169,"url":"https://github.com/tox-dev/tox-uv","last_synced_at":"2026-05-05T03:06:54.700Z","repository":{"id":222853539,"uuid":"758362225","full_name":"tox-dev/tox-uv","owner":"tox-dev","description":"Use https://github.com/astral-sh/uv with tox","archived":false,"fork":false,"pushed_at":"2026-04-27T17:15:52.000Z","size":341,"stargazers_count":342,"open_issues_count":1,"forks_count":37,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-03T23:39:05.465Z","etag":null,"topics":["tox"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tox-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yaml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"tidelift":"pypi/tox-uv"}},"created_at":"2024-02-16T06:37:58.000Z","updated_at":"2026-04-27T17:15:54.000Z","dependencies_parsed_at":"2024-03-18T18:52:48.042Z","dependency_job_id":"8e8fb808-2408-4eb8-bd4e-93021e72c6fa","html_url":"https://github.com/tox-dev/tox-uv","commit_stats":null,"previous_names":["tox-dev/tox-uv"],"tags_count":72,"template":false,"template_full_name":null,"purl":"pkg:github/tox-dev/tox-uv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-uv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-uv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-uv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-uv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tox-dev","download_url":"https://codeload.github.com/tox-dev/tox-uv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-uv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32633446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"online","status_checked_at":"2026-05-05T02:00:06.033Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["tox"],"created_at":"2024-11-17T14:26:43.583Z","updated_at":"2026-05-05T03:06:54.657Z","avatar_url":"https://github.com/tox-dev.png","language":"Python","funding_links":["https://tidelift.com/funding/github/pypi/tox-uv"],"categories":[],"sub_categories":[],"readme":"# tox-uv\n\n[![PyPI version](https://badge.fury.io/py/tox-uv.svg)](https://badge.fury.io/py/tox-uv)\n[![PyPI Supported Python Versions](https://img.shields.io/pypi/pyversions/tox-uv.svg)](https://pypi.python.org/pypi/tox-uv/)\n[![check](https://github.com/tox-dev/tox-uv/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/tox-uv/actions/workflows/check.yaml)\n[![Downloads](https://static.pepy.tech/badge/tox-uv/month)](https://pepy.tech/project/tox-uv)\n\n**tox-uv** is a `tox` plugin, which replaces `virtualenv` and pip with `uv` in your `tox` environments. Note that you\nwill get both the benefits (performance) or downsides (bugs) of `uv`.\n\n\u003c!--ts--\u003e\n\n- [How to use](#how-to-use)\n  - [Installation options](#installation-options)\n  - [uv discovery](#uv-discovery)\n- [tox environment types provided](#tox-environment-types-provided)\n- [PEP 723 inline script metadata](#pep-723-inline-script-metadata)\n- [uv.lock support](#uvlock-support)\n  - [package](#package)\n  - [extras](#extras)\n  - [no_default_groups](#no_default_groups)\n  - [dependency_groups](#dependency_groups)\n  - [only_groups](#only_groups)\n  - [uv_sync_flags](#uv_sync_flags)\n  - [uv_sync_locked](#uv_sync_locked)\n  - [External package support](#external-package-support)\n- [Environment creation](#environment-creation)\n  - [uv_seed](#uv_seed)\n  - [uv_python_preference](#uv_python_preference)\n- [Package installation](#package-installation)\n- [uv_resolution](#uv_resolution)\n\n\u003c!--te--\u003e\n\n## How to use\n\nInstall `tox-uv` into the environment of your tox, and it will replace `virtualenv` and `pip` for all runs:\n\n```bash\nuv tool install tox --with tox-uv # use uv to install\ntox --version # validate you are using the installed tox\ntox r -e py312 # will use uv\ntox --runner virtualenv r -e py312 # will use virtualenv+pip\n```\n\n### Installation options\n\n`tox-uv` is distributed as two packages:\n\n- **`tox-uv`** (recommended): Meta package that includes both the plugin and a bundled `uv` binary. This ensures `uv` is\n  always available and provides the best out-of-box experience.\n\n- **`tox-uv-bare`**: Plugin-only package without the bundled `uv` binary. Use this in containerized environments\n  (Docker, Kubernetes) where `uv` is pre-installed in the system to avoid downloading duplicate binaries.\n\nExample Docker usage with `tox-uv-bare`:\n\n```dockerfile\nFROM python:3.12\nRUN pip install uv tox tox-uv-bare\n# uv is already in the container, no need to bundle it again\n```\n\n### uv discovery\n\n`tox-uv` discovers the `uv` binary in the following order:\n\n1. **`TOX_UV_PATH` environment variable**: Explicitly specify the `uv` binary location. Useful for testing custom `uv`\n   builds or when `uv` is installed in a non-standard location.\n\n   ```bash\n   export TOX_UV_PATH=/custom/path/to/uv\n   tox r\n   ```\n\n1. **Bundled `uv`** (when using `tox-uv` meta package): Uses the `uv` binary included with the `tox-uv` package.\n\n1. **System `uv`** (when using `tox-uv-bare` or if bundled `uv` not found): Searches for `uv` in your system `PATH`.\n\nIf `uv` cannot be found, `tox-uv` will raise an error with installation instructions.\n\n## tox environment types provided\n\nThis package will provide the following new tox environments:\n\n- `uv-venv-runner` is the ID for the tox environments [runner](https://tox.wiki/en/4.12.1/config.html#runner) for\n  environments not using a lock file.\n- `uv-venv-lock-runner` is the ID for the tox environments [runner](https://tox.wiki/en/4.12.1/config.html#runner) for\n  environments using `uv.lock` (note we can’t detect the presence of the `uv.lock` file to enable this because that\n  would break environments not using the lock file - such as your linter).\n- `uv-venv-pep-723` is the ID for the [PEP 723](https://peps.python.org/pep-0723/) inline script metadata runner. When\n  `tox-uv` is installed, `virtualenv-pep-723` is also transparently backed by uv.\n- `uv-venv-pep-517` is the ID for the PEP-517 packaging environment.\n- `uv-venv-cmd-builder` is the ID for the external cmd builder.\n\n## PEP 723 inline script metadata\n\n[PEP 723](https://peps.python.org/pep-0723/) lets Python scripts declare their dependencies and required Python version\ninline via comment blocks.\n\nGiven a script `tools/check.py`:\n\n```python\n# /// script\n# requires-python = \"\u003e=3.12\"\n# dependencies = [\"requests\u003e=2.31\", \"rich\"]\n# ///\n\nimport requests\nfrom rich import print\n\nprint(requests.get(\"https://httpbin.org/get\").json())\n```\n\nConfigure tox to run it:\n\n```ini\n[testenv:check]\nrunner = virtualenv-pep-723\nscript = tools/check.py\n```\n\nWhen `tox-uv` is installed, `virtualenv-pep-723` is transparently backed by uv. You can also use\n`runner = uv-venv-pep-723` to explicitly request the uv-backed runner regardless of plugin installation.\n\nTo disable the automatic promotion and use tox's built-in virtualenv+pip implementation, set `TOX_UV_NO_PEP723=1`.\n\nRun with `tox r -e check`. Positional arguments are forwarded: `tox r -e check -- --verbose`.\n\nTo override the default command (which runs the script), set `commands` as usual:\n\n```ini\n[testenv:check]\nrunner = virtualenv-pep-723\nscript = tools/check.py\ncommands = python -m pytest tests/\n```\n\n## uv.lock support\n\nIf you want for a tox environment to use `uv sync` with a `uv.lock` file you need to change for that tox environment the\n`runner` to `uv-venv-lock-runner`. Furthermore, should in such environments you use the `extras` config to instruct `uv`\nto install the specified extras, for example (this example is for the `tox.ini`, for other formats see the documentation\n[here](https://tox.wiki/en/latest/config.html#discovery-and-file-types)):\n\n```ini\n\n[testenv:fix]\ndescription = run code formatter and linter (auto-fix)\nskip_install = true\ndeps =\n    pre-commit-uv\u003e=4.1.1\ncommands =\n    pre-commit run --all-files --show-diff-on-failure\n\n[testenv:type]\nrunner = uv-venv-lock-runner\ndescription = run type checker via mypy\ncommands =\n    mypy {posargs:src}\n\n[testenv:dev]\nrunner = uv-venv-lock-runner\ndescription = dev environment\nextras =\n    dev\n    test\n    type\ncommands =\n    uv pip tree\n```\n\nIn this example:\n\n- `fix` will use the `uv-venv-runner` and use `uv pip install` to install dependencies to the environment.\n- `type` will use the `uv-venv-lock-runner` and use `uv sync` to install dependencies to the environment without any\n  extra group.\n- `dev` will use the `uv-venv-lock-runner` and use `uv sync` to install dependencies to the environment with the `dev`,\n  `test` and `type` extra groups.\n\nNote that when using `uv-venv-lock-runner`, _all_ dependencies will come from the lock file, controlled by `extras`.\nTherefore, options like `deps` are ignored (and all others\n[enumerated here](https://tox.wiki/en/stable/config.html#python-run) as Python run flags).\n\n### `package`\n\nHow to install the source tree package, must be one of:\n\n- `skip` - do not install the project,\n- `wheel` - install the project as a non-editable wheel,\n- `editable` (default) - install the project in editable mode,\n- `uv` - with `uv-venv-runner` uses uv directly to install the project (bypassing tox's PEP-517 packaging), with\n  `uv-venv-lock-runner` behaves like `wheel`,\n- `uv-editable` - with `uv-venv-runner` uses uv directly to install in editable mode (bypassing tox's PEP-517\n  packaging), with `uv-venv-lock-runner` behaves like `editable`.\n\nWith `uv-venv-runner`, prefer `uv`/`uv-editable` when you need non-standard features of `uv`, such as `tool.uv.sources`.\nWith `uv-venv-lock-runner`, `uv sync` already handles installation natively so all modes work through it.\n\n### `extras`\n\nA list of string that selects, which extra groups you want to install with `uv sync`. By default, it is empty.\n\n### `no_default_groups`\n\nA boolean flag to toggle installation of the `uv`\n[default development groups](https://docs.astral.sh/uv/concepts/projects/dependencies/#default-groups). By default, it\nwill be `true` if the `dependency_groups` is not empty and `false` otherwise.\n\n### `dependency_groups`\n\nSpecify [PEP 735 – Dependency Groups](https://peps.python.org/pep-0735/) to install **in addition to** the project and\nits dependencies (maps to `uv sync --group`). For example, `dependency_groups = [\"test\", \"docs\"]` installs the project,\nits default dependencies, and the `test` and `docs` groups.\n\n### `only_groups`\n\nInstall **only** these [PEP 735 – Dependency Groups](https://peps.python.org/pep-0735/), excluding the project and all\nother dependencies (maps to `uv sync --only-group`). Use this when you need a dependency group in complete isolation,\nsuch as CI tooling from a private index. For example, `only_groups = [\"ci\"]` installs only the `ci` group without the\nproject or any of its dependencies.\n\n**Key difference**: `dependency_groups` adds groups to the standard install, while `only_groups` replaces the entire\ninstall with just those groups.\n\n### `uv_sync_flags`\n\nA list of strings, containing additional flags to pass to uv sync (useful because some flags are not configurable via\nenvironment variables). For example, if you want to install the package in non editable mode and keep extra packages\ninstalled into the environment you can do:\n\n```ini\nuv_sync_flags = --no-editable, --inexact\n```\n\nIf `--frozen` is included in `uv_sync_flags`, tox-uv will automatically suppress the implicit `--locked` argument since\nthe two flags are mutually exclusive in uv:\n\n```ini\nuv_sync_flags = --frozen\n```\n\n### `uv_sync_locked`\n\nBy default tox-uv will call `uv sync` with `--locked` argument, which is incompatible with other arguments like\n`--prerelease` or `--upgrade ` that you might want to add to `uv_sync_flags` for some test scenarios. You can set this\nto `false` to avoid such conflicts.\n\nIf the `UV_FROZEN` environment variable is set to a truthy value, tox-uv will automatically suppress `--locked` and pass\n`--frozen` to `uv sync` instead. This is useful in CI environments where the lockfile was created on a different\nplatform and platform-specific metadata validation should be skipped:\n\n```bash\nUV_FROZEN=1 tox\n```\n\n### External package support\n\nShould tox be invoked with the [`--installpkg`](https://tox.wiki/en/stable/cli_interface.html#tox-run---installpkg) flag\n(the argument **must** be either a wheel or source distribution) the sync operation will run with `--no-install-project`\nand `uv pip install` will be used afterward to install the provided package.\n\n## Environment creation\n\nWe use `uv venv` to create virtual environments. This process can be configured with the following options:\n\n### `uv_seed`\n\nThis flag, set on a tox environment level, controls if the created virtual environment injects `pip`, `setuptools` and\n`wheel` into the created virtual environment or not. By default, it is off. You will need to set this if you have a\nproject that uses the old legacy-editable mode, or your project doesn’t support the `pyproject.toml` powered isolated\nbuild model.\n\n### `uv_python_preference`\n\nThis flag, set on a tox environment level, controls how `uv` select the Python interpreter.\n\nBy default, `uv` will attempt to use Python versions found on the system and only download managed interpreters when\nnecessary. However, It is possible to adjust `uv`'s Python version selection preference with the\n[python-preference](https://docs.astral.sh/uv/concepts/python-versions/#adjusting-python-version-preferences) option.\n\n### `system_site_packages` (`sitepackages`)\n\nCreate virtual environments that also have access to globally installed packages. Note the default value may be\noverwritten by the VIRTUALENV_SYSTEM_SITE_PACKAGES environment variable. This flag works the same way as the one from\n[tox native virtualenv implementation](https://tox.wiki/en/latest/config.html#system_site_packages).\n\n## Package installation\n\nWe use `uv pip` to install packages into the virtual environment. The behavior of this can be configured via the\nfollowing options:\n\n### `uv_resolution`\n\nThis flag, set on a tox environment level, informs `uv` of the desired [resolution strategy]:\n\n- `highest` - (default) selects the highest version of a package satisfying the constraints.\n- `lowest` - install the **lowest** compatible versions for all dependencies, both **direct** and **transitive**.\n- `lowest-direct` - opt for the **lowest** compatible versions for all **direct** dependencies, while using the\n  **latest** compatible versions for all **transitive** dependencies.\n\nThis is an `uv` specific feature that may be used as an alternative to frozen constraints for test environments if the\nintention is to validate the lower bounds of your dependencies during test executions.\n\n**Note**: When using `uv_resolution` with `dependency_groups`, all dependencies from both `deps` and `dependency_groups`\nare combined into a single install operation. This ensures the resolution strategy applies correctly across all\nrequirements, preventing sequential installations from resolving transitive dependencies before the strategy can apply\nto overlapping direct dependencies.\n\n### Cache invalidation for `UV_*` environment variables\n\ntox-uv includes a curated set of `UV_*` environment variables in the install cache key. When any of these variables\nchange via `set_env`, the cached environment is invalidated and packages are reinstalled so that uv can re-resolve with\nthe new settings. The tracked variables are:\n\n`UV_CONSTRAINT`, `UV_DEFAULT_INDEX`, `UV_EXCLUDE`, `UV_EXCLUDE_NEWER`, `UV_EXTRA_INDEX_URL`, `UV_FIND_LINKS`,\n`UV_FORK_STRATEGY`, `UV_INDEX`, `UV_INDEX_STRATEGY`, `UV_INDEX_URL`, `UV_KEYRING_PROVIDER`, `UV_NO_INDEX`,\n`UV_NO_SOURCES`, `UV_OFFLINE`, `UV_OVERRIDE`, `UV_PRERELEASE`, `UV_REQUIRE_HASHES`, `UV_RESOLUTION`, `UV_TORCH_BACKEND`.\n\nVariables that do not affect resolution (e.g. `UV_CONCURRENT_DOWNLOADS`, `UV_NO_PROGRESS`, `UV_CACHE_DIR`) are not\ntracked and changing them will not trigger a reinstall.\n\n[resolution strategy]: https://github.com/astral-sh/uv/blob/0.1.20/README.md#resolution-strategy\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftox-dev%2Ftox-uv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftox-dev%2Ftox-uv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftox-dev%2Ftox-uv/lists"}