uv tool install

Install commands provided by a Python package into an isolated environment

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 cpython@3.12 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/repo.git@v1.0.0

# 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

• uv tool run - Run a tool without installing it
• uv tool list - List installed tools
• uv tool uninstall - Uninstall a tool
• uv tool update-shell - Add tool directory to PATH