Skip to main content

​
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: 
uvx ruff
uvx is an alias for uv tool run. Use whichever you prefer!

​
Passing arguments

Arguments are passed after the tool name: 
uvx pycowsay hello from uv

#   -------------
# < hello from uv >
#   -------------
#    \   ^__^
#     \  (oo)\_______
#        (__)\       )\/\
#            ||----w |
#            ||     ||
Tools run in temporary, isolated environments.
If running a tool in a project that requires the project to be installed (e.g., pytest, mypy), use uv run 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.

​
Commands with different package names

Sometimes package and command names differ. Use --from to specify the package: 
# The 'http' command is provided by 'httpie'
uvx --from httpie http

​
Requesting specific versions

uvx [email protected] check
The @ syntax only works for exact versions. Use --from for version ranges.

​
Requesting extras

Run tools with optional dependencies: 
uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

​
Requesting different sources

The --from option supports alternative sources: 
uvx --from git+https://github.com/httpie/cli httpie

​
Commands with plugins

Include additional dependencies: 
uvx --with mkdocs-material mkdocs --help

​
Installing tools

For frequently-used tools, install them to a persistent environment:
All tool management commands require the full uv tool prefix (except uvx, which is an alias for uv tool run).
1

Install the tool

uv tool install ruff
Tool executables are placed in a bin directory added to your PATH.
2

Verify installation

ruff --version
If it’s not on the PATH, use uv tool update-shell to add it.

​
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
# This will fail - tools are isolated
python -c "import ruff"

​
Installing with options

uv tool install 'httpie>0.1.0'

​
Upgrading tools

1

Upgrade a single tool

uv tool upgrade ruff
Upgrades respect the version constraints provided during installation.
2

Replace version constraints

Re-install with new constraints:
uv tool install ruff>=0.4
3

Upgrade all tools

uv tool upgrade --all
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.

​
Requesting Python versions

By default, uv uses your default Python interpreter. Specify a different version: 
uvx --python 3.10 ruff
See Python version requests for more details.

​
Legacy Windows scripts

Tools support running legacy setuptools scripts on Windows. Scripts are available via $(uv tool dir)\<tool-name>\Scripts when installed. 
uv tool run --from nuitka==2.6.7 nuitka.cmd --version
uvx automatically looks for files ending in .ps1, .cmd, and .bat in that order.

​
Complete workflow examples

​
Quick one-off tool usage

# 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

1

Install your toolchain

uv tool install ruff
uv tool install mypy
uv tool install pytest
2

Use tools directly

ruff check .
mypy src/
pytest tests/
3

Keep tools updated

uv tool upgrade --all

​
Running tools with plugins

# 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

Tools concept

Learn more about tool management

Command reference

View all uv tool commands

Working with projects

Manage Python projects

Python versions

Manage Python installations

Build docs developers (and LLMs) love

Get started for freeTalk to us