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 installation. When invoked, uvx resolves the requested package, creates a short-lived environment, executes the tool’s entry point, and discards the environment afterward.

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

Common commands

Run a tool once

# Run the latest version of ruff
uvx ruff check .

# Run a specific version
uvx [email protected] 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:

# 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

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:

uvx --with numpy ipython

Install a tool permanently

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

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

How uvx compares to pipx

pipx 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? for the full breakdown.

Learn More

• When to use uv run vs uvx
• How do uv tool and pipx compare?
• How to install Python CLI tools without Python
• uv tool management documentation
• uv reference page
• pipx reference page