> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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.

<Note>
  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.
</Note>

## Examples

### Install a tool

```bash theme={null}
uv tool install ruff
```

### Install a specific version

```bash theme={null}
uv tool install ruff==0.3.0
```

### Install with version constraint

```bash theme={null}
uv tool install "ruff>=0.3.0,<0.4.0"
```

### Install with extras

```bash theme={null}
uv tool install "myapp[dev,test]"
```

### Install with additional dependencies

```bash theme={null}
uv tool install myapp --with pandas --with numpy
```

### Install from Git

```bash theme={null}
uv tool install git+https://github.com/user/repo.git
```

### Install in editable mode

```bash theme={null}
uv tool install --editable ./my-package
```

### Force reinstall

```bash theme={null}
uv tool install --force ruff
```

## Arguments

<ParamField path="PACKAGE" type="string" required>
  The package to install commands from. Can be a package name, a package with version specifier, a URL, or a local path.

  ```bash theme={null}
  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
  ```
</ParamField>

## Options

### Package Options

<ParamField path="--from" type="string">
  The package to install commands from. This option is provided for parity with `uv tool run`, but is redundant with the `PACKAGE` argument.

  ```bash theme={null}
  uv tool install --from black black
  ```
</ParamField>

<ParamField path="-w, --with" type="string">
  Include additional requirements. Can be specified multiple times.

  ```bash theme={null}
  uv tool install myapp --with pandas --with numpy
  ```
</ParamField>

<ParamField path="--with-requirements" type="file">
  Run with the packages listed in the given files. Supports `requirements.txt`, `.py` files with inline metadata, and `pylock.toml`.

  ```bash theme={null}
  uv tool install myapp --with-requirements requirements.txt
  ```
</ParamField>

<ParamField path="-e, --editable" type="boolean">
  Install the target package in editable mode, such that changes in the package's source directory are reflected without reinstallation.

  ```bash theme={null}
  uv tool install --editable ./my-package
  ```
</ParamField>

<ParamField path="--with-editable" type="path">
  Include the given packages in editable mode. Can be specified multiple times.

  ```bash theme={null}
  uv tool install myapp --with-editable ./dependency
  ```
</ParamField>

<ParamField path="--with-executables-from" type="string">
  Install executables from the specified packages. This allows you to install commands from additional packages beyond the main package.

  ```bash theme={null}
  uv tool install myapp --with-executables-from extra-tools
  ```
</ParamField>

### Constraints

<ParamField path="-c, --constraint" type="file">
  Constrain versions using the given requirements files. Constraints files only control the version of a requirement but don't trigger installation.

  ```bash theme={null}
  uv tool install -c constraints.txt ruff
  ```
</ParamField>

<ParamField path="--override" type="file">
  Override versions using the given requirements files. Overrides force a specific version regardless of other requirements.

  ```bash theme={null}
  uv tool install --override overrides.txt myapp
  ```
</ParamField>

<ParamField path="--exclude" type="file">
  Exclude packages from resolution using the given requirements files. Excludes are unconditional - any package listed will be omitted from all resolved environments.

  ```bash theme={null}
  uv tool install --exclude excludes.txt myapp
  ```
</ParamField>

<ParamField path="--build-constraint" type="file">
  Constrain build dependencies using the given requirements files when building source distributions.

  ```bash theme={null}
  uv tool install --build-constraint build-constraints.txt myapp
  ```
</ParamField>

### Installation Options

<ParamField path="--force" type="boolean">
  Force installation of the tool. Will replace any existing entry points with the same name in the executable directory.

  ```bash theme={null}
  uv tool install --force ruff
  ```
</ParamField>

### Python Options

<ParamField path="-p, --python" type="string">
  The Python interpreter to use to build the tool environment.

  See `uv help python` for details on Python discovery and supported request formats.

  ```bash theme={null}
  uv tool install --python 3.11 myapp
  uv tool install --python cpython@3.12 myapp
  ```
</ParamField>

<ParamField path="--python-platform" type="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`).

  <Warning>
    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.
  </Warning>

  ```bash theme={null}
  uv tool install --python-platform aarch64-apple-darwin myapp
  ```
</ParamField>

### PyTorch Options

<ParamField path="--torch-backend" type="string">
  The backend to use when fetching packages in the PyTorch ecosystem (e.g., `cpu`, `cu126`, or `auto`).

  <Note>
    This option is in preview and may change in future releases.
  </Note>

  ```bash theme={null}
  uv tool install --torch-backend cu126 myapp
  ```
</ParamField>

### Git Options

<ParamField path="--lfs" type="boolean">
  Whether to use Git LFS when adding a dependency from Git.

  ```bash theme={null}
  uv tool install --lfs git+https://example.com/repo.git
  ```
</ParamField>

## Version and Extras Specification

### Specifying versions

You can specify package versions using standard Python version specifiers:

```bash theme={null}
# 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:

```bash theme={null}
# Single extra
uv tool install "myapp[dev]"

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

### Installing from alternative sources

```bash theme={null}
# 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

```bash theme={null}
# 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`:

```bash theme={null}
uv tool update-shell
```

Then restart your shell or run:

```bash theme={null}
source ~/.bashrc  # or ~/.zshrc, etc.
```

### Installation fails due to conflicts

Use `--force` to replace existing installations:

```bash theme={null}
uv tool install --force ruff
```

### Python version incompatibility

Specify a compatible Python version:

```bash theme={null}
uv tool install --python 3.11 myapp
```

### Checking installed tool location

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

```bash theme={null}
uv tool list --show-paths
```

### Reinstalling a tool

To completely reinstall a tool:

```bash theme={null}
uv tool uninstall ruff
uv tool install ruff
```

## See Also

* [uv tool run](/cli/tool-run) - Run a tool without installing it
* [uv tool list](/cli/tool-list) - List installed tools
* [uv tool uninstall](/cli/tool-uninstall) - Uninstall a tool
* [uv tool update-shell](/cli/tool-update-shell) - Add tool directory to PATH