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

# Using Tools

> Run and install Python tools with uvx and uv tool commands

## Overview

Many Python packages provide command-line tools. uv has specialized support for easily invoking and installing tools without polluting your project environments.

## Running tools with uvx

The `uvx` command invokes a tool without installing it:

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

<Note>
  `uvx` is an alias for `uv tool run`. Use whichever you prefer!
</Note>

### Passing arguments

Arguments are passed after the tool name:

```bash theme={null}
uvx pycowsay hello from uv

#   -------------
# < hello from uv >
#   -------------
#    \   ^__^
#     \  (oo)\_______
#        (__)\       )\/\
#            ||----w |
#            ||     ||
```

Tools run in temporary, isolated environments.

<Warning>
  If running a tool in a [project](../concepts/projects/index.md) that requires the project to be installed (e.g., `pytest`, `mypy`), use [`uv run`](./projects.mdx#running-commands) instead. Otherwise, the tool runs in an isolated environment without access to your project.

  For flat project structures (no `src` directory), `uvx` works fine. Use `uv run` if you want to pin the tool version in project dependencies.
</Warning>

## Commands with different package names

Sometimes package and command names differ. Use `--from` to specify the package:

```bash theme={null}
# The 'http' command is provided by 'httpie'
uvx --from httpie http
```

## Requesting specific versions

<CodeGroup>
  ```bash Specific version theme={null}
  uvx ruff@0.3.0 check
  ```

  ```bash Latest version theme={null}
  uvx ruff@latest check
  ```

  ```bash Version with --from theme={null}
  uvx --from 'ruff==0.3.0' ruff check
  ```

  ```bash Version range theme={null}
  uvx --from 'ruff>0.2.0,<0.3.0' ruff check
  ```
</CodeGroup>

<Note>
  The `@` syntax only works for exact versions. Use `--from` for version ranges.
</Note>

## Requesting extras

Run tools with optional dependencies:

<CodeGroup>
  ```bash With extras theme={null}
  uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report
  ```

  ```bash Extras with version theme={null}
  uvx --from 'mypy[faster-cache,reports]==1.13.0' mypy --xml-report mypy_report
  ```
</CodeGroup>

## Requesting different sources

The `--from` option supports alternative sources:

<CodeGroup>
  ```bash From Git theme={null}
  uvx --from git+https://github.com/httpie/cli httpie
  ```

  ```bash Specific branch theme={null}
  uvx --from git+https://github.com/httpie/cli@master httpie
  ```

  ```bash Specific tag theme={null}
  uvx --from git+https://github.com/httpie/cli@3.2.4 httpie
  ```

  ```bash Specific commit theme={null}
  uvx --from git+https://github.com/httpie/cli@2843b87 httpie
  ```

  ```bash With Git LFS theme={null}
  uvx --lfs --from git+https://github.com/astral-sh/lfs-cowsay lfs-cowsay
  ```
</CodeGroup>

## Commands with plugins

Include additional dependencies:

```bash theme={null}
uvx --with mkdocs-material mkdocs --help
```

## Installing tools

For frequently-used tools, install them to a persistent environment:

<Tip>
  All tool management commands require the full `uv tool` prefix (except `uvx`, which is an alias for `uv tool run`).
</Tip>

<Steps>
  <Step title="Install the tool">
    ```bash theme={null}
    uv tool install ruff
    ```

    Tool executables are placed in a `bin` directory added to your `PATH`.
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    ruff --version
    ```

    If it's not on the `PATH`, use `uv tool update-shell` to add it.
  </Step>
</Steps>

### Installation behavior

Unlike `uv pip install`, tool installation:

* Installs all executables provided by the package
* Isolates the tool from other environments
* Does not make modules importable in other environments

```bash theme={null}
# This will fail - tools are isolated
python -c "import ruff"
```

### Installing with options

<CodeGroup>
  ```bash Version constraint theme={null}
  uv tool install 'httpie>0.1.0'
  ```

  ```bash From Git theme={null}
  uv tool install git+https://github.com/httpie/cli
  ```

  ```bash With Git LFS theme={null}
  uv tool install --lfs git+https://github.com/astral-sh/lfs-cowsay
  ```

  ```bash With plugins theme={null}
  uv tool install mkdocs --with mkdocs-material
  ```

  ```bash Multiple executables theme={null}
  uv tool install --with-executables-from ansible-core,ansible-lint ansible
  ```
</CodeGroup>

## Upgrading tools

<Steps>
  <Step title="Upgrade a single tool">
    ```bash theme={null}
    uv tool upgrade ruff
    ```

    Upgrades respect the version constraints provided during installation.
  </Step>

  <Step title="Replace version constraints">
    Re-install with new constraints:

    ```bash theme={null}
    uv tool install ruff>=0.4
    ```
  </Step>

  <Step title="Upgrade all tools">
    ```bash theme={null}
    uv tool upgrade --all
    ```
  </Step>
</Steps>

<Note>
  If you installed `ruff>=0.3,<0.4`, running `uv tool upgrade ruff` will upgrade to the latest version within that range, not beyond it.
</Note>

## Requesting Python versions

By default, uv uses your default Python interpreter. Specify a different version:

<CodeGroup>
  ```bash Run with specific Python theme={null}
  uvx --python 3.10 ruff
  ```

  ```bash Install with specific Python theme={null}
  uv tool install --python 3.10 ruff
  ```

  ```bash Upgrade with specific Python theme={null}
  uv tool upgrade --python 3.10 ruff
  ```
</CodeGroup>

See [Python version requests](../concepts/python-versions.md#requesting-a-version) for more details.

## Legacy Windows scripts

Tools support running [legacy setuptools scripts](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#scripts) on Windows.

Scripts are available via `$(uv tool dir)\<tool-name>\Scripts` when installed.

<CodeGroup>
  ```powershell With extension theme={null}
  uv tool run --from nuitka==2.6.7 nuitka.cmd --version
  ```

  ```powershell Auto-detect extension theme={null}
  uv tool run --from nuitka==2.6.7 nuitka --version
  ```
</CodeGroup>

`uvx` automatically looks for files ending in `.ps1`, `.cmd`, and `.bat` in that order.

## Complete workflow examples

### Quick one-off tool usage

```bash theme={null}
# Format code with the latest ruff
uvx ruff@latest format .

# Run a presentation with slides
uvx --from slides slides serve presentation.md

# Create a new project with cookiecutter
uvx cookiecutter gh:audreyr/cookiecutter-pypackage
```

### Installing frequently-used tools

<Steps>
  <Step title="Install your toolchain">
    ```bash theme={null}
    uv tool install ruff
    uv tool install mypy
    uv tool install pytest
    ```
  </Step>

  <Step title="Use tools directly">
    ```bash theme={null}
    ruff check .
    mypy src/
    pytest tests/
    ```
  </Step>

  <Step title="Keep tools updated">
    ```bash theme={null}
    uv tool upgrade --all
    ```
  </Step>
</Steps>

### Running tools with plugins

```bash theme={null}
# Run mkdocs with theme plugin
uvx --with mkdocs-material mkdocs serve

# Run jupyter with specific kernel
uvx --with ipykernel jupyter notebook

# Run pylint with plugins
uvx --with pylint-django --with pylint-celery pylint src/
```

## Next steps

<CardGroup cols={2}>
  <Card title="Tools concept" icon="wrench" href="../concepts/tools.md">
    Learn more about tool management
  </Card>

  <Card title="Command reference" icon="terminal" href="../reference/cli.md#uv-tool">
    View all uv tool commands
  </Card>

  <Card title="Working with projects" icon="folder" href="./projects.mdx">
    Manage Python projects
  </Card>

  <Card title="Python versions" icon="snake" href="../concepts/python-versions.md">
    Manage Python installations
  </Card>
</CardGroup>