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.

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"

[envs.default]
installer = "uv"

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",
]

[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"] },
]

[[envs.example.matrix]]
tool = ["uv", "pip"]

[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}"

[envs.hatch-test.extra-scripts]
pip = "{env:HATCH_UV} pip {args}"