Back to Details

uv-tool-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UV Tool Management

UV 工具管理

Quick reference for installing and managing global Python tools with UV (pipx alternative).
使用 UV（pipx 的替代方案）安装和管理全局 Python 工具的快速参考。

When to Use This Skill

何时使用此 Skill

Use this skill when...Use a focused sibling instead when...
Installing a global CLI tool (ruff, black, ipython) with 
uv tool install
as a pipx replacement		Running a project script inside its venv — use uv-run
Running a one-off CLI invocation via 
uvx tool
without installing		Adding the tool as a project dev dependency — use uv-project-management
Listing, upgrading, or uninstalling globally installed toolsPinning the Python version a tool runs on — use uv-python-versions
使用此 Skill 的场景应改用专门的同级 Skill 的场景
使用 
uv tool install
安装全局 CLI 工具（如 ruff、black、ipython），作为 pipx 的替代方案		在项目的 venv 中运行脚本——使用 uv-run
通过 
uvx tool
运行一次性 CLI，无需安装		将工具添加为项目开发依赖——使用 uv-project-management
列出、升级或卸载全局安装的工具固定工具运行所用的 Python 版本——使用 uv-python-versions

When This Skill Applies

此 Skill 的适用场景

  • Installing command-line tools globally (like pipx)
  • Managing tool installations and updates
  • Running tools ephemerally without installation
  • Listing and removing installed tools
  • Tool version management
  • 全局安装命令行工具（如 pipx）
  • 管理工具安装和更新
  • 临时运行工具，无需安装
  • 列出和移除已安装的工具
  • 管理工具版本

Quick Reference

快速参考

Installing Tools

安装工具

bash
undefined
bash
undefined

Install tool globally

Install tool globally

uv tool install ruff uv tool install black uv tool install pytest
uv tool install ruff uv tool install black uv tool install pytest

Install specific version

Install specific version

uv tool install ruff@0.1.0 uv tool install 'pytest>=7.0'
uv tool install ruff@0.1.0 uv tool install 'pytest>=7.0'

Install from Git

Install from Git

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

Install with extras

Install with extras

uv tool install 'mkdocs[i18n]' uv tool install 'fastapi[all]'
undefined
uv tool install 'mkdocs[i18n]' uv tool install 'fastapi[all]'
undefined

Running Tools

运行工具

bash
undefined
bash
undefined

Run without installing (ephemeral)

Run without installing (ephemeral)

uvx pycowsay "hello world" uvx ruff check . uvx black --check .
uvx pycowsay "hello world" uvx ruff check . uvx black --check .

uvx is alias for:

uvx is alias for:

uv tool run pycowsay "hello world"
uv tool run pycowsay "hello world"

Run with specific version

Run with specific version

uvx ruff@0.1.0 check .
uvx ruff@0.1.0 check .

Run from Git

Run from Git

uvx git+https://github.com/user/tool script.py
undefined
uvx git+https://github.com/user/tool script.py
undefined

Managing Tools

管理工具

bash
undefined
bash
undefined

List installed tools

List installed tools

uv tool list
uv tool list

Update tool

Update tool

uv tool install ruff --reinstall uv tool upgrade ruff
uv tool install ruff --reinstall uv tool upgrade ruff

Remove tool

Remove tool

uv tool uninstall ruff
uv tool uninstall ruff

Remove all tools

Remove all tools

uv tool uninstall --all
undefined
uv tool uninstall --all
undefined

Tool Information

工具信息

bash
undefined
bash
undefined

Check tool version

Check tool version

ruff --version
ruff --version

List tool binaries

List tool binaries

uv tool list --verbose
uv tool list --verbose

Show tool location

Show tool location

which ruff
which ruff

~/.local/bin/ruff (Linux)

~/.local/bin/ruff (Linux)

~/Library/Application Support/uv/bin/ruff (macOS)

~/Library/Application Support/uv/bin/ruff (macOS)

undefined
undefined

uvx vs uv tool run

uvx 与 uv tool run 对比

These commands are equivalent:
bash
uvx ruff check .
uv tool run ruff check .
uvx
is a convenient shorthand for ephemeral tool execution.
以下命令等价：
bash
uvx ruff check .
uv tool run ruff check .
uvx
是临时执行工具的便捷简写。

Installation Locations

安装位置

Tools Directory

工具目录

bash
undefined
bash
undefined

Linux

Linux

~/.local/share/uv/tools/
~/.local/share/uv/tools/

macOS

macOS

~/Library/Application Support/uv/tools/
~/Library/Application Support/uv/tools/

Windows

Windows

%LOCALAPPDATA%\uv\tools\
undefined
%LOCALAPPDATA%\uv\tools\
undefined

Binaries (Executables)

二进制文件（可执行文件）

bash
undefined
bash
undefined

Linux

Linux

~/.local/bin/
~/.local/bin/

macOS

macOS

~/Library/Application Support/uv/bin/
~/Library/Application Support/uv/bin/

Windows

Windows

%LOCALAPPDATA%\uv\bin\

**Add to PATH:**
```bash
%LOCALAPPDATA%\uv\bin\

**添加到 PATH：**
```bash

Add to ~/.bashrc or ~/.zshrc

Add to ~/.bashrc or ~/.zshrc

export PATH="$HOME/.local/bin:$PATH"
undefined
export PATH="$HOME/.local/bin:$PATH"
undefined

Common Tools

常用工具

bash
undefined
bash
undefined

Code quality

Code quality

uv tool install ruff uv tool install black uv tool install ty
uv tool install ruff uv tool install black uv tool install ty

Documentation

Documentation

uv tool install mkdocs uv tool install sphinx
uv tool install mkdocs uv tool install sphinx

Testing

Testing

uv tool install pytest uv tool install tox
uv tool install pytest uv tool install tox

Build tools

Build tools

uv tool install build uv tool install twine
uv tool install build uv tool install twine

Utilities

Utilities

uv tool install httpie uv tool install pipx uv tool install cookiecutter
undefined
uv tool install httpie uv tool install pipx uv tool install cookiecutter
undefined

UV Tool vs Project Dependencies

UV Tool 与项目依赖

Use 
uv tool
for:
  • Command-line applications
  • Global development tools
  • Utilities used across projects
Use 
uv add
for:
  • Project-specific dependencies
  • Libraries imported in code
  • Development dependencies in specific projects
bash
undefined
使用 
uv tool
：
  • 命令行应用程序
  • 全局开发工具
  • 跨项目使用的实用工具
使用 
uv add
：
  • 项目专用依赖
  • 在代码中导入的库
  • 特定项目中的开发依赖
bash
undefined

Global tool (any project)

Global tool (any project)

uv tool install ruff
uv tool install ruff

Project dependency (one project)

Project dependency (one project)

uv add --dev ruff
undefined
uv add --dev ruff
undefined

Tool Isolation

工具隔离

Each tool gets its own virtual environment:
bash
undefined
每个工具都会获得独立的虚拟环境：
bash
undefined

Each tool is isolated

Each tool is isolated

~/.local/share/uv/tools/ ├── ruff/ # Isolated environment for ruff ├── black/ # Isolated environment for black └── pytest/ # Isolated environment for pytest
~/.local/share/uv/tools/ ├── ruff/ # Isolated environment for ruff ├── black/ # Isolated environment for black └── pytest/ # Isolated environment for pytest

No dependency conflicts between tools

No dependency conflicts between tools

undefined
undefined

Common Workflows

常见工作流

Setup Development Tools

设置开发工具

bash
undefined
bash
undefined

Install common development tools globally

Install common development tools globally

uv tool install ruff uv tool install ty uv tool install pytest uv tool install ipython
uv tool install ruff uv tool install ty uv tool install pytest uv tool install ipython

Now available in any project

Now available in any project

ruff check . ty check src/ pytest ipython
undefined
ruff check . ty check src/ pytest ipython
undefined

One-Off Tool Usage

一次性工具使用

bash
undefined
bash
undefined

Run without installing

Run without installing

uvx pycowsay "Temporary tool!" uvx httpie https://api.github.com
uvx pycowsay "Temporary tool!" uvx httpie https://api.github.com

No cleanup needed

No cleanup needed

undefined
undefined

Replace pipx

替换 pipx

bash
undefined
bash
undefined

Old (pipx)

Old (pipx)

pipx install black pipx run pycowsay "hello"
pipx install black pipx run pycowsay "hello"

New (uv)

New (uv)

uv tool install black uvx pycowsay "hello"
undefined
uv tool install black uvx pycowsay "hello"
undefined

Key Features

主要功能

  • Fast: 10-100x faster than pipx
  • Isolated: Each tool in separate environment
  • Ephemeral: Run tools without installation
  • Version control: Pin tool versions
  • Git support: Install from repositories
  • 快速：比 pipx 快 10-100 倍
  • 隔离：每个工具使用独立环境
  • 临时运行：无需安装即可运行工具
  • 版本管理：固定工具版本
  • Git 支持：从仓库安装

See Also

相关 Skill

  • uv-project-management
    - Project-specific dependencies
  • uv-python-versions
    - Python versions for tools
  • python-code-quality
    - Using ruff, ty, black
  • uv-project-management
    - 项目专用依赖
  • uv-python-versions
    - 工具所用的 Python 版本
  • python-code-quality
    - 使用 ruff、ty、black

References

参考资料