Skip to main content

​
uv tool install

Install commands provided by a Python package into an isolated environment.

​
Usage

uv tool install [OPTIONS] <PACKAGE>

​
Description

Packages are installed into an isolated virtual environment in the uv tools directory. The executables are linked to the tool executable directory, which is determined according to the XDG standard and can be retrieved with uv tool dir --bin. If the tool was previously installed, the existing tool will generally be replaced.
After installing a tool, you may need to add the tool executable directory to your PATH. Use uv tool update-shell to do this automatically.

​
Examples

​
Install a tool

uv tool install ruff

​
Install a specific version

uv tool install ruff==0.3.0

​
Install with version constraint

uv tool install "ruff>=0.3.0,<0.4.0"

​
Install with extras

uv tool install "myapp[dev,test]"

​
Install with additional dependencies

uv tool install myapp --with pandas --with numpy

​
Install from Git

uv tool install git+https://github.com/user/repo.git

​
Install in editable mode

uv tool install --editable ./my-package

​
Force reinstall

uv tool install --force ruff

​
Arguments

​
PACKAGE
string
required
The package to install commands from. Can be a package name, a package with version specifier, a URL, or a local path.
uv tool install ruff
uv tool install "ruff>=0.3.0"
uv tool install git+https://github.com/user/repo.git
uv tool install ./local-package

​
Options

​
Package Options

​
--from
string
The package to install commands from. This option is provided for parity with uv tool run, but is redundant with the PACKAGE argument.
uv tool install --from black black
​
-w, --with
string
Include additional requirements. Can be specified multiple times.
uv tool install myapp --with pandas --with numpy
​
--with-requirements
file
Run with the packages listed in the given files. Supports requirements.txt, .py files with inline metadata, and pylock.toml.
uv tool install myapp --with-requirements requirements.txt
​
-e, --editable
boolean
Install the target package in editable mode, such that changes in the package’s source directory are reflected without reinstallation.
uv tool install --editable ./my-package
​
--with-editable
path
Include the given packages in editable mode. Can be specified multiple times.
uv tool install myapp --with-editable ./dependency
​
--with-executables-from
string
Install executables from the specified packages. This allows you to install commands from additional packages beyond the main package.
uv tool install myapp --with-executables-from extra-tools

​
Constraints

​
-c, --constraint
file
Constrain versions using the given requirements files. Constraints files only control the version of a requirement but don’t trigger installation.
uv tool install -c constraints.txt ruff
​
--override
file
Override versions using the given requirements files. Overrides force a specific version regardless of other requirements.
uv tool install --override overrides.txt myapp
​
--exclude
file
Exclude packages from resolution using the given requirements files. Excludes are unconditional - any package listed will be omitted from all resolved environments.
uv tool install --exclude excludes.txt myapp
​
--build-constraint
file
Constrain build dependencies using the given requirements files when building source distributions.
uv tool install --build-constraint build-constraints.txt myapp

​
Installation Options

​
--force
boolean
Force installation of the tool. Will replace any existing entry points with the same name in the executable directory.
uv tool install --force ruff

​
Python Options

​
-p, --python
string
The Python interpreter to use to build the tool environment.See uv help python for details on Python discovery and supported request formats.
uv tool install --python 3.11 myapp
uv tool install --python [email protected] myapp
​
--python-platform
string
The platform for which requirements should be installed. Represented as a “target triple” (e.g., x86_64-unknown-linux-gnu or aarch64-apple-darwin).
This option is for advanced use cases. When specified, uv will select wheels compatible with the target platform, which may not be compatible with the current platform.
uv tool install --python-platform aarch64-apple-darwin myapp

​
PyTorch Options

​
--torch-backend
string
The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).
This option is in preview and may change in future releases.
uv tool install --torch-backend cu126 myapp

​
Git Options

​
--lfs
boolean
Whether to use Git LFS when adding a dependency from Git.
uv tool install --lfs git+https://example.com/repo.git

​
Version and Extras Specification

​
Specifying versions

You can specify package versions using standard Python version specifiers: 
# Exact version
uv tool install ruff==0.3.0

# Minimum version
uv tool install "ruff>=0.3.0"

# Version range
uv tool install "ruff>=0.3.0,<0.4.0"

# Compatible release
uv tool install "ruff~=0.3.0"

​
Installing with extras

Install packages with optional extras: 
# Single extra
uv tool install "myapp[dev]"

# Multiple extras
uv tool install "myapp[dev,test]"

​
Installing from alternative sources

# From Git
uv tool install git+https://github.com/user/repo.git
uv tool install git+https://github.com/user/[email protected]

# From URL
uv tool install https://example.com/package.whl

# From local path
uv tool install ./local-package
uv tool install ../another-package

​
Tool Environment Location

Tools are installed in the uv data directory:
  • Unix: $XDG_DATA_HOME/uv/tools or $HOME/.local/share/uv/tools
  • Windows: %APPDATA%\uv\data\tools
You can override this location with the UV_TOOL_DIR environment variable.

​
Finding the tool directory

# Show tools directory
uv tool dir

# Show executables directory
uv tool dir --bin

​
Troubleshooting

​
Command not found after installation

Ensure the tool executable directory is on your PATH: 
uv tool update-shell
Then restart your shell or run: 
source ~/.bashrc  # or ~/.zshrc, etc.

​
Installation fails due to conflicts

Use --force to replace existing installations: 
uv tool install --force ruff

​
Python version incompatibility

Specify a compatible Python version: 
uv tool install --python 3.11 myapp

​
Checking installed tool location

Use uv tool list --show-paths to see where tools are installed: 
uv tool list --show-paths

​
Reinstalling a tool

To completely reinstall a tool: 
uv tool uninstall ruff
uv tool install ruff

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us