> ## 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 run

> Run a command provided by a Python package in an isolated environment

# uv tool run

Run a command provided by a Python package in an isolated environment.

## Aliases

* `uvx` - Convenient shorthand for `uv tool run`

## Usage

```bash theme={null}
uv tool run [OPTIONS] [COMMAND]
uvx [OPTIONS] [COMMAND]
```

## Description

By default, the package to install is assumed to match the command name. The command name can include an exact version in the format `<package>@<version>`, e.g., `uv tool run ruff@0.3.0`.

If the tool was previously installed via `uv tool install`, the installed version will be used unless a version is requested or the `--isolated` flag is used.

Packages are installed into an ephemeral virtual environment in the uv cache directory.

<Tip>
  `uvx` is provided as a convenient alias for `uv tool run`. Their behavior is identical.
</Tip>

## Examples

### Run a tool with default version

```bash theme={null}
uvx ruff check .
```

### Run a specific version

```bash theme={null}
uvx ruff@0.3.0 check .
```

### Run a tool from a different package

```bash theme={null}
uv tool run --from black blackd
```

### Run with additional dependencies

```bash theme={null}
uvx --with pandas --with numpy ipython
```

### Run Python in an isolated environment

```bash theme={null}
uvx python
uvx python@3.11
```

### Run with requirements file

```bash theme={null}
uvx --with-requirements requirements.txt myapp
```

## Options

### Package Selection

<ParamField path="--from" type="string">
  Use the given package to provide the command. By default, the package name is assumed to match the command name.

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

<ParamField path="-w, --with" type="string">
  Run with the given packages installed. Can be specified multiple times.

  ```bash theme={null}
  uvx --with pandas --with numpy ipython
  ```
</ParamField>

<ParamField path="--with-editable" type="path">
  Run with the given packages installed in editable mode. When used in a project, these dependencies will be layered on top of the tool's environment in a separate, ephemeral environment.

  ```bash theme={null}
  uv tool run --with-editable ./my-package myapp
  ```
</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}
  uvx --with-requirements requirements.txt myapp
  ```
</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 run -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 run --override overrides.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 run --build-constraint build-constraints.txt myapp
  ```
</ParamField>

### Environment Options

<ParamField path="--isolated" type="boolean">
  Run the tool in an isolated virtual environment, ignoring any already-installed tools.

  ```bash theme={null}
  uvx --isolated ruff check .
  ```
</ParamField>

<ParamField path="--env-file" type="file">
  Load environment variables from a `.env` file. Can be provided multiple times, with subsequent files overriding previous values.

  ```bash theme={null}
  uv tool run --env-file .env --env-file .env.local myapp
  ```
</ParamField>

<ParamField path="--no-env-file" type="boolean">
  Avoid reading environment variables from a `.env` file.

  ```bash theme={null}
  uvx --no-env-file myapp
  ```
</ParamField>

### Python Options

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

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

  ```bash theme={null}
  uvx --python 3.11 myapp
  uvx --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 run --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}
  uvx --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 run --lfs --from git+https://example.com/repo.git myapp
  ```
</ParamField>

### Advanced Options

<ParamField path="--show-resolution" type="boolean">
  Whether to show resolver and installer output from any environment modifications. By default, environment modifications are omitted but enabled under `--verbose`.

  ```bash theme={null}
  uvx --show-resolution myapp
  ```
</ParamField>

## Version Specification

You can specify package versions in several ways:

### Exact version

```bash theme={null}
uvx ruff@0.3.0 check .
```

### Version constraint with --from

```bash theme={null}
uv tool run --from "ruff>=0.3.0,<0.4.0" ruff check .
```

### Latest version (default)

```bash theme={null}
uvx ruff check .
```

## Extras Specification

Install packages with optional extras:

```bash theme={null}
# Single extra
uvx --from "myapp[dev]" myapp

# Multiple extras
uvx --from "myapp[dev,test]" myapp
```

## Troubleshooting

### Command not found

If a command isn't found, ensure the package name matches the command or use `--from`:

```bash theme={null}
# Wrong - 'black' package doesn't provide 'blackd' by default in command name
uvx blackd

# Correct - specify the package explicitly
uv tool run --from black blackd
```

### Version conflicts

If you encounter version conflicts, use `--isolated` to ignore existing installations:

```bash theme={null}
uvx --isolated ruff@0.2.0 check .
```

### Cache issues

If you experience cache-related problems, clear the cache:

```bash theme={null}
uv cache clean
uvx ruff check .
```

### Environment not activating

Ensure you're not inside an active virtual environment that might interfere:

```bash theme={null}
deactivate  # Exit any active environment
uvx myapp
```

## See Also

* [uv tool install](/cli/tool-install) - Install a tool for repeated use
* [uv tool list](/cli/tool-list) - List installed tools
* [uv tool uninstall](/cli/tool-uninstall) - Uninstall a tool
* [uv run](/guides/scripts) - Run scripts in a project context