# uvx: Run Python CLI Tools in Isolated Environments


uvx is a command that runs Python CLI tools in temporary, isolated virtual environments. It is an alias for `uv tool run`, included with every [uv](https://pydevtools.com/handbook/reference/uv.md) installation. When invoked, uvx resolves the requested package, creates a short-lived environment, executes the tool's entry point, and discards the environment afterward.

> [!NOTE]
> uvx ships with uv. There is no separate installation step. If uv is installed, uvx is available.

## When to use uvx

Use uvx to run a Python CLI tool without adding it to a project's dependencies or polluting the global environment. Typical cases: one-off linting or formatting passes, scaffolding a new project with a cookiecutter template, running a utility to inspect a file. If the tool needs access to your project's own packages, use [`uv run`](https://pydevtools.com/handbook/explanation/when-to-use-uv-run-vs-uvx.md) instead.

## Common commands

### Run a tool once

```bash
# Run the latest version of ruff
uvx ruff check .

# Run a specific version
uvx ruff@0.11.0 check .
```

uvx fetches the package, caches it, runs the command, and exits. Subsequent runs of the same version resolve from cache in milliseconds.

### Run a tool from a different package name

Some packages expose an entry point whose name differs from the package name on PyPI. Use `--from` to specify the package:

```bash
# The "httpie" package provides the "http" command
uvx --from httpie http https://example.com

# The "jupyter" metapackage provides the "jupyter" command
uvx --from jupyter jupyter notebook
```

### Run with a specific Python version

```bash
uvx --python 3.11 ruff check .
```

uv downloads the requested Python version automatically if it is not already installed.

### Run with extra dependencies

Some tools need additional packages available at runtime. Use `--with` to inject them:

```bash
uvx --with numpy ipython
```

### Install a tool permanently

To keep a tool available across sessions instead of running it ephemerally, use `uv tool install`:

```bash
# Install ruff globally
uv tool install ruff

# List installed tools
uv tool list

# Upgrade a tool
uv tool upgrade ruff

# Upgrade all tools
uv tool upgrade --all

# Uninstall a tool
uv tool uninstall ruff
```

`uv tool install` places the tool's entry point on `PATH` (in `~/.local/bin` by default) with its own isolated environment, similar to how [pipx](https://pydevtools.com/handbook/reference/pipx.md) works.

## How uvx compares to pipx

[pipx](https://pydevtools.com/handbook/reference/pipx.md) pioneered the per-tool-venv pattern; uvx follows the same model with a different runtime profile:

- **Speed.** uvx uses uv's resolver and shared cache. A cold `uvx ruff --version` takes around one second on a typical laptop; the cached follow-up runs in tens of milliseconds. pipx with its default pip backend takes several seconds for the same cold install.
- **Bundled with uv.** No separate install or Python prerequisite. pipx is its own package that requires Python already on the machine.
- **Built-in Python management.** `uvx --python 3.13` downloads CPython 3.13 if not present. pipx uses whichever Python is already installed.
- **Cache lifetime.** uvx reuses cached environments until pruned, pinned, or refreshed. `pipx run` expires its temp venv after 14 idle days.
- **Persistent install precedence.** After `uv tool install ruff`, plain `uvx ruff` reuses that environment instead of building an ephemeral one. `pipx run` ignores any matching `pipx install`.

`uv tool` and `uvx` cover most pipx use cases, but pipx still owns `pipx inject`, `--suffix`, `--global`, and `pipx install-all` (no uvx equivalents). See [How do uv tool and pipx compare?](https://pydevtools.com/handbook/explanation/how-do-uv-tool-and-pipx-compare.md) for the full breakdown.

## Learn More

- [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.
- [When to use `uv run` vs `uvx`](https://pydevtools.com/handbook/explanation/when-to-use-uv-run-vs-uvx.md)
- [How do uv tool and pipx compare?](https://pydevtools.com/handbook/explanation/how-do-uv-tool-and-pipx-compare.md)
- [How to install Python CLI tools without Python](https://pydevtools.com/handbook/how-to/how-to-install-python-cli-tools-without-python.md)
- [uv tool management documentation](https://docs.astral.sh/uv/guides/tools/)
- [uv reference page](https://pydevtools.com/handbook/reference/uv.md)
- [pipx reference page](https://pydevtools.com/handbook/reference/pipx.md)