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:

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

Specific version

uvx ruff@0.3.0 check

uvx ruff@latest check

uvx --from 'ruff==0.3.0' ruff check

uvx --from 'ruff>0.2.0,<0.3.0' ruff check

The @ syntax only works for exact versions. Use --from for version ranges.

Requesting extras

Run tools with optional dependencies:

With extras

uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

uvx --from 'mypy[faster-cache,reports]==1.13.0' mypy --xml-report mypy_report

Requesting different sources

The --from option supports alternative sources:

From Git

uvx --from git+https://github.com/httpie/cli httpie

uvx --from git+https://github.com/httpie/cli@master httpie

uvx --from git+https://github.com/httpie/cli@3.2.4 httpie

uvx --from git+https://github.com/httpie/cli@2843b87 httpie

uvx --lfs --from git+https://github.com/astral-sh/lfs-cowsay lfs-cowsay

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

Version constraint

uv tool install 'httpie>0.1.0'

uv tool install git+https://github.com/httpie/cli

uv tool install --lfs git+https://github.com/astral-sh/lfs-cowsay

uv tool install mkdocs --with mkdocs-material

uv tool install --with-executables-from ansible-core,ansible-lint ansible

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:

Run with specific Python

uvx --python 3.10 ruff

uv tool install --python 3.10 ruff

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

With extension

uv tool run --from nuitka==2.6.7 nuitka.cmd --version

uv tool run --from nuitka==2.6.7 nuitka --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