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 idea of running Python CLI tools in isolated environments. uvx provides the same concept with several differences:

• No separate install. uvx comes with uv. pipx is a standalone tool that requires Python to already be present.
• Speed. uvx uses uv’s resolver and global cache, making cold installs and warm runs significantly faster.
• Python version management. uvx can download and use any Python version via --python. pipx uses whichever Python is already on the system.
• Ephemeral by default. uvx <tool> runs and discards. pipx run <tool> behaves similarly, but pipx’s primary workflow is permanent installation with pipx install.

For most users, uvx replaces pipx entirely. The pipx reference page has more detail on pipx-specific features.

Learn More

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