2.7 KiB
How to select the installer
Enabling UV
The virtual environment type by default uses virtualenv for virtual environment creation and pip to install dependencies. You can speed up environment creation and dependency resolution by using UV instead of both of those tools.
!!! warning "caveat" UV is under active development and may not work for all dependencies.
To do so, set the installer option to uv. For example, if you wanted to enable this functionality for the default environment, you could set the following:
[tool.hatch.envs.default]
installer = "uv"
!!! tip
All environments that enable UV will have the path to UV available as the HATCH_UV environment variable.
Configuring the version
The UV that is shared by all environments uses a specific version range that is known to work with Hatch. If you want to use a different version, you can override the dependencies for the internal hatch-uv environment:
[tool.hatch.envs.hatch-uv]
dependencies = [
"uv>9000",
]
Externally managed
If you want to manage UV yourself, you can expose it to Hatch by setting the HATCH_ENV_TYPE_VIRTUAL_UV_PATH environment variable which should be the absolute path to a UV binary for Hatch to use instead. This implicitly enables UV.
Installer script alias
If you have scripts or commands that call pip, it may be useful to alias the uv pip command to pip so that you can use the same commands for both methods of configuration and retain your muscle memory. The following is an example of a matrix that conditionally enables UV and sets the alias:
[[tool.hatch.envs.example.matrix]]
tool = ["uv", "pip"]
[tool.hatch.envs.example.overrides]
matrix.tool.installer = { value = "{matrix:tool}" }
matrix.tool.scripts = [
{ key = "pip", value = "{env:HATCH_UV} pip {args}", if = ["uv"] },
]
Another common use case is to expose UV to all test environments. In this case, you often wouldn't want to modify the scripts mapping directly but rather add an extra script:
[tool.hatch.envs.hatch-test.extra-scripts]
pip = "{env:HATCH_UV} pip {args}"