# tox-uv
[](https://badge.fury.io/py/tox-uv)
[](https://pypi.python.org/pypi/tox-uv/)
[](https://github.com/tox-dev/tox-uv/actions/workflows/check.yaml)
[](https://pepy.tech/project/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`.
<!--ts-->
- [How to use](#how-to-use)
- [tox environment types provided](#tox-environment-types-provided)
- [uv.lock support](#uvlock-support)
- [extras](#extras)
- [with_dev](#with_dev)
- [External package support](#external-package-support)
- [Environment creation](#environment-creation)
- [uv_seed](#uv_seed)
- [uv_python_preference](#uv_python_preference)
- [Package installation](#package-installation)
- [uv_resolution](#uv_resolution)
<!--te-->
## How to use
Install `tox-uv` into the environment of your tox, and it will replace `virtualenv` and `pip` for all runs:
```bash
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
```
## tox environment types provided
This package will provide the following new tox environments:
- `uv-venv-runner` is the ID for the tox environments [runner](https://tox.wiki/en/4.12.1/config.html#runner) for
environments not using a lock file.
- `uv-venv-lock-runner` is the ID for the tox environments [runner](https://tox.wiki/en/4.12.1/config.html#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-517` is the ID for the PEP-517 packaging environment.
- `uv-venv-cmd-builder` is the ID for the external cmd builder.
## 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:
```ini
[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](https://tox.wiki/en/stable/config.html#python-run) as Python run flags).
### `extras`
A list of string that selects, which extra groups you want to install with `uv sync`. By default, it is empty.
### `with_dev`
A boolean flag to toggle installation of the `uv` development dependencies. By default, it is false.
### `dependency_groups`
Specify [PEP 735 – Dependency Groups](https://peps.python.org/pep-0735/) to install.
### `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:
```ini
uv_sync_flags = --no-editable, --inexact
```
### External package support
Should tox be invoked with the [`--installpkg`](https://tox.wiki/en/stable/cli_interface.html#tox-run---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](https://docs.astral.sh/uv/concepts/python-versions/#adjusting-python-version-preferences) option.
## 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.
[resolution strategy]: https://github.com/astral-sh/uv/blob/0.1.20/README.md#resolution-strategy
Raw data
{
"_id": null,
"home_page": null,
"name": "tox-uv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Bern\u00e1t G\u00e1bor <gaborjbernat@gmail.com>",
"keywords": "environments, isolated, testing, virtual",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ed/5e/c3d2a45ab5465dddbbc267a589c9cfce23b91750d49af10738a08c98534e/tox_uv-1.16.0.tar.gz",
"platform": null,
"description": "# tox-uv\n\n[](https://badge.fury.io/py/tox-uv)\n[](https://pypi.python.org/pypi/tox-uv/)\n[](https://github.com/tox-dev/tox-uv/actions/workflows/check.yaml)\n[](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<!--ts-->\n\n- [How to use](#how-to-use)\n- [tox environment types provided](#tox-environment-types-provided)\n- [uv.lock support](#uvlock-support)\n - [extras](#extras)\n - [with_dev](#with_dev)\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 <!--te-->\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## 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\u2019t 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-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## 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:\n\n```ini\n\n[testenv:fix]\ndescription = run code formatter and linter (auto-fix)\nskip_install = true\ndeps =\n pre-commit-uv>=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### `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### `with_dev`\n\nA boolean flag to toggle installation of the `uv` development dependencies. By default, it is false.\n\n### `dependency_groups`\n\nSpecify [PEP 735 \u2013 Dependency Groups](https://peps.python.org/pep-0735/) to install.\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\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\u2019t 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## 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[resolution strategy]: https://github.com/astral-sh/uv/blob/0.1.20/README.md#resolution-strategy\n",
"bugtrack_url": null,
"license": null,
"summary": "Integration of uv with tox.",
"version": "1.16.0",
"project_urls": {
"Changelog": "https://github.com/tox-dev/tox-uv/releases",
"Documentation": "https://github.com/tox-dev/tox-uv#tox-uv",
"Homepage": "https://github.com/tox-dev/tox-uv",
"Source": "https://github.com/tox-dev/tox-uv",
"Tracker": "https://github.com/tox-dev/tox-uv/issues"
},
"split_keywords": [
"environments",
" isolated",
" testing",
" virtual"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad8d1baa9f725ddd4824708759cf7b74bc43379f5f7feb079fde0629d7b32b3e",
"md5": "8ee5de7a151dd4229140179059eb8f45",
"sha256": "e6f0b525a687e745ab878d07cbf5c7e85d582028d4a7c8935f95e84350651432"
},
"downloads": -1,
"filename": "tox_uv-1.16.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ee5de7a151dd4229140179059eb8f45",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13661,
"upload_time": "2024-10-30T17:47:54",
"upload_time_iso_8601": "2024-10-30T17:47:54.893110Z",
"url": "https://files.pythonhosted.org/packages/ad/8d/1baa9f725ddd4824708759cf7b74bc43379f5f7feb079fde0629d7b32b3e/tox_uv-1.16.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ed5ec3d2a45ab5465dddbbc267a589c9cfce23b91750d49af10738a08c98534e",
"md5": "5f596025d9b48f3ab60b91ed3c580c75",
"sha256": "71b2e2fa6c35c1360b91a302df1d65b3e5a1f656b321c5ebf7b84545804c9f01"
},
"downloads": -1,
"filename": "tox_uv-1.16.0.tar.gz",
"has_sig": false,
"md5_digest": "5f596025d9b48f3ab60b91ed3c580c75",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 16337,
"upload_time": "2024-10-30T17:47:56",
"upload_time_iso_8601": "2024-10-30T17:47:56.390620Z",
"url": "https://files.pythonhosted.org/packages/ed/5e/c3d2a45ab5465dddbbc267a589c9cfce23b91750d49af10738a08c98534e/tox_uv-1.16.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-30 17:47:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tox-dev",
"github_project": "tox-uv",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "tox-uv"
}
JSON
