uv tool install: Install CLI Tools Globally
uv tool install puts a Python command-line tool into its own isolated environment and exposes its entry points on PATH.
uv tool install is the pipx-style command for global CLIs like ruff or black. Each tool gets an isolated environment so their dependencies never collide.
What it does
uv tool install creates a dedicated virtual environment for the named package, installs it there, and links its executables into the uv tool bin directory. The tool is then available globally without polluting any project environment.
Common usage
uv tool install ruff
uv tool install black==24.10.0
uv tool install --with mypy-extensions mypy
uv tool install --python 3.12 poetry
uv tool listOptions
| Flag | What it does |
|---|---|
| --with <pkg> | Add extra packages into the tool environment |
| --force | Reinstall even if already present |
| --python <version> | Build the tool environment on a specific Python |
| --editable | Install a local path tool in editable mode |
| --upgrade | Upgrade the tool to the latest compatible version |
In CI
Run uv tool update-shell or ensure the uv tool bin dir is on PATH; otherwise the installed command is not found. In ephemeral runners, uvx (uv tool run) is often better than install because it needs no PATH wiring. Cache $UV_CACHE_DIR to skip re-downloading the tool each run.
Common errors in CI
"warning: <tool> is installed but not on your PATH" means the bin directory is missing from PATH; add it or run uv tool update-shell. "error: Failed to install entrypoints ... already exists" means a name clash; use --force. If the package has no scripts, uv prints "No executables are provided by <pkg>".