uv Tool Management

uv 工具管理

Purpose

用途

This skill teaches you how to efficiently manage Python command-line tools using uv, including running tools on-demand without installation, installing persistent tools globally, managing versions, and understanding when to use tools versus project dependencies.

本技能将教你如何使用uv高效管理Python命令行工具，包括无需安装即可按需运行工具、全局安装持久化工具、管理版本，以及理解何时使用工具而非项目依赖。

Quick Start

快速开始

Run any CLI tool without installing it:

bash

undefined

无需安装即可运行任意CLI工具：

bash

undefined

Run ruff (Python linter) once without installation

无需安装，一次性运行ruff（Python代码检查工具）

uvx ruff check .

Equivalent longer form

等效的完整写法

uv tool run ruff check .

Install a tool permanently for repeated use

持久化安装工具以重复使用

uv tool install ruff

Then run the installed tool

运行已安装的工具

ruff check .

undefined

ruff check .

undefined

Instructions

操作指南

Step 1: Understand the Tool Management Landscape

步骤1：了解工具管理场景

uv replaces

pipx

for tool management. There are three main approaches:

uvx (temporary execution): Run a tool once without installation

Tool is fetched, cached, and executed in an isolated environment
No modification to your system
Ideal for: occasional use, trying tools, CI/CD where tools aren't needed repeatedly

uv tool install (persistent installation): Install a tool for repeated use

Tool is installed globally in a dedicated environment
Available in PATH after installation
Ideal for: tools you use regularly (linters, formatters, test runners)

uv run (project environment): Run tools that need access to your project

Tools run within your project's virtual environment
Can access your project's installed packages
Ideal for: testing, linting, formatting your project code

uv可替代

pipx

进行工具管理，主要有三种使用方式：

uvx（临时执行）：无需安装即可一次性运行工具

工具会被拉取、缓存并在隔离环境中执行
不会对系统进行任何修改
适用场景：偶尔使用的工具、试用新工具、无需重复使用工具的CI/CD流程

uv tool install（持久化安装）：安装工具以重复使用

工具会被全局安装在专用环境中
安装后可在PATH中直接访问
适用场景：日常频繁使用的工具（代码检查器、格式化工具、测试运行器）

uv run（项目环境）：运行需要访问项目资源的工具

工具在项目的虚拟环境中运行
可访问项目已安装的依赖包
适用场景：对项目代码进行测试、代码检查、格式化

Step 2: Choose Between uvx and uv tool install

步骤2：选择uvx与uv tool install的使用场景

Use
uvx
(ephemeral) when:

Running a tool for the first time to test it
Tool is used rarely or on-demand
You want no installation footprint
Running in CI/CD pipelines (cleaner, no persistent state)
Tool has conflicting dependencies with other tools

bash

undefined

使用
uvx
（临时）的场景：

首次试用新工具
工具使用频率低或仅按需使用
不想留下安装痕迹
在CI/CD流水线中运行（更简洁，无持久化状态）
工具与其他工具存在依赖冲突

bash

undefined

Try a new tool without committing to it

试用新工具，无需长期安装

uvx httpie https://api.github.com/users/github

Run a tool on-demand in CI

在CI中按需运行工具

uvx mypy src/

Run tool from different package

运行来自不同包的工具

uvx --from httpie http https://example.com


**Use `uv tool install` (persistent) when:**
- Tool is part of your regular workflow
- Team uses it consistently (document in README)
- Tool provides utility functions beyond single invocation
- You want faster execution (no download overhead each time)
- Tool is referenced in project docs or scripts

```bash

uvx --from httpie http https://example.com


**使用`uv tool install`（持久化）的场景：**
- 工具是日常工作流的一部分
- 团队成员一致使用（可在README中记录）
- 工具提供单次调用之外的实用功能
- 希望更快执行（无需每次下载）
- 工具在项目文档或脚本中被引用

```bash

Install tools you use daily

安装日常使用的工具

uv tool install ruff uv tool install black uv tool install mypy

Then run directly without prefix

直接运行，无需前缀

ruff check . black --check src/ mypy src/


**Use `uv run` (project environment) when:**
- Running tests, linters, or formatters on your project
- Tool needs access to project dependencies
- Running from within project directory
- Tool is listed in project's dev dependencies

```bash

ruff check . black --check src/ mypy src/


**使用`uv run`（项目环境）的场景：**
- 对项目代码进行测试、代码检查或格式化
- 工具需要访问项目依赖
- 在项目目录内运行
- 工具被列为项目的开发依赖

```bash

Test runner needs access to project (test libraries, modules)

测试运行器需要访问项目资源（测试库、模块）

uv run pytest tests/

Linter running on project code

对项目代码进行类型检查

uv run mypy src/

Format project code

格式化项目代码

uv run black src/

undefined

uv run black src/

undefined

Step 3: Run Tools with uvx

步骤3：使用uvx运行工具

Basic execution without arguments:

bash

uvx ruff check .
uvx black --check src/

Specify exact version:

bash

undefined

不带参数的基础执行：

bash

uvx ruff check .
uvx black --check src/

指定精确版本：

bash

undefined

Run specific version of a tool

运行工具的特定版本

uvx ruff@0.3.0 check .

Use version constraint

使用版本约束

uvx --from 'ruff>=0.3.0,<0.4.0' ruff check .


**Run tools from different packages:**
```bash

uvx --from 'ruff>=0.3.0,<0.4.0' ruff check .


**运行来自不同包的工具：**
```bash

httpie is in package 'httpie', command is 'http'

httpie属于包'httpie'，命令为'http'

uvx --from httpie http https://api.github.com

mkdocs is in 'mkdocs', command is 'mkdocs'

mkdocs属于包'mkdocs'，命令为'mkdocs'

uvx mkdocs serve


**Include optional dependencies (extras):**
```bash

uvx mkdocs serve


**包含可选依赖（extras）：**
```bash

mypy with optional faster caching

启用了快速缓存可选依赖的mypy

uvx --from 'mypy[faster-cache]' mypy src/

mkdocs with material theme

搭配mkdocs-material主题的mkdocs

uvx --with mkdocs-material mkdocs serve


**Run with specific Python version:**
```bash

uvx --with mkdocs-material mkdocs serve


**使用特定Python版本运行：**
```bash

Run tool with Python 3.10 (useful for compatibility testing)

使用Python 3.10运行工具（适用于兼容性测试）

uvx --python 3.10 ruff check .

Ensure tool runs on minimum supported version

使用最低支持版本运行工具

uvx --python 3.9 pytest tests/


**Run from git repository:**
```bash

uvx --python 3.9 pytest tests/


**从Git仓库运行：**
```bash

Install directly from GitHub

直接从GitHub安装并运行

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

undefined

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

undefined

Step 4: Install and Manage Persistent Tools

步骤4：安装与管理持久化工具

Install tools:

bash

undefined

安装工具：

bash

undefined

Install latest version

安装最新版本

uv tool install ruff

Install specific version

安装特定版本

uv tool install ruff@0.3.0

Install with extras

安装包含可选依赖的工具

uv tool install 'mypy[faster-cache]'

Install from git

从Git仓库安装

uv tool install git+https://github.com/user/tool


**List installed tools:**
```bash
uv tool list

uv tool install git+https://github.com/user/tool


**查看已安装工具：**
```bash
uv tool list

Example output:

示例输出：

black 0.23.11 /Users/user/.local/bin/black

mypy 1.7.0 /Users/user/.local/bin/mypy

ruff 0.3.0 /Users/user/.local/bin/ruff


**Upgrade tools:**
```bash


**升级工具：**
```bash

Upgrade specific tool to latest

将特定工具升级到最新版本

uv tool upgrade ruff

Upgrade all tools

升级所有工具

uv tool upgrade --all

Upgrade to specific version

升级到特定版本

uv tool upgrade ruff@0.4.0


**Uninstall tools:**
```bash

uv tool upgrade ruff@0.4.0


**卸载工具：**
```bash

Remove installed tool

卸载已安装的工具

uv tool uninstall ruff

Remove multiple tools

卸载多个工具

uv tool uninstall ruff black mypy

undefined

uv tool uninstall ruff black mypy

undefined

Step 5: Understand Tool vs Project Dependencies

步骤5：理解工具依赖与项目依赖的区别

Critical distinction for your workflow:

toml

undefined

工作流中的关键区分：

toml

undefined

pyproject.toml

[project]

Main project dependencies - needed to run your application

项目核心依赖 - 运行应用所必需

dependencies = [ "fastapi>=0.104.0", "httpx>=0.27.0", ]

[project.optional-dependencies]

dependencies = [ "fastapi>=0.104.0", "httpx>=0.27.0", ]

[project.optional-dependencies]

Optional features for your application (not development tools)

应用的可选功能（非开发工具）

aws = ["boto3>=1.34.0"] database = ["sqlalchemy>=2.0.0"]

[dependency-groups]

aws = ["boto3>=1.34.0"] database = ["sqlalchemy>=2.0.0"]

[dependency-groups]

Development tools - only needed while developing

开发工具 - 仅在开发过程中需要

test = [ "pytest>=8.0.0", "pytest-cov>=4.1.0", ] lint = [ "ruff>=0.1.0", "mypy>=1.7.0", ] format = [ "black>=23.11.0", ]


**Decision matrix:**

| Use Case | Tool | Command | Where |
|----------|------|---------|-------|
| Try a new linter | uvx | `uvx flake8 .` | Any directory |
| Lint project code regularly | uv run | `uv run ruff check .` | Project directory |
| Lint tool used across projects | uv tool install | `ruff check .` | Any directory |
| Test code | uv run | `uv run pytest` | Project directory |
| Build documentation | uv tool install | `uv tool install mkdocs` | Global install |
| One-time script execution | uvx | `uvx httpie` | Any directory |
| Format code | uv run | `uv run black src/` | Project directory |

test = [ "pytest>=8.0.0", "pytest-cov>=4.1.0", ] lint = [ "ruff>=0.1.0", "mypy>=1.7.0", ] format = [ "black>=23.11.0", ]


**决策矩阵：**

| 使用场景 | 工具 | 命令 | 运行位置 |
|----------|------|---------|-------|
| 试用新的代码检查工具 | uvx | `uvx flake8 .` | 任意目录 |
| 定期对项目代码进行检查 | uv run | `uv run ruff check .` | 项目目录 |
| 跨多个项目使用的代码检查工具 | uv tool install | `ruff check .` | 任意目录 |
| 测试代码 | uv run | `uv run pytest` | 项目目录 |
| 构建文档 | uv tool install | `uv tool install mkdocs` | 全局安装 |
| 一次性脚本执行 | uvx | `uvx httpie` | 任意目录 |
| 格式化代码 | uv run | `uv run black src/` | 项目目录 |

Step 6: Manage Tool Versions and Upgrades

步骤6：管理工具版本与升级

Check installed version:

bash

undefined

查看已安装版本：

bash

undefined

Show version of installed tool

查看已安装工具的版本

ruff --version

Or via uv

或通过uv查看

uv tool list | grep ruff


**Upgrade specific tool:**
```bash

uv tool list | grep ruff


**升级特定工具：**
```bash

Upgrade to latest

升级到最新版本

uv tool upgrade ruff

Keep all tools up to date

保持所有工具为最新版本

uv tool upgrade --all


**Pin tool version:**
```bash

uv tool upgrade --all


**固定工具版本：**
```bash

Use specific version (best practice for team consistency)

使用特定版本（团队协作的最佳实践）

uv tool install ruff@0.3.0

Override installed version

覆盖已安装的版本

uv tool install ruff@0.4.0


**Clean up old tools:**
```bash

uv tool install ruff@0.4.0


**清理旧工具：**
```bash

Uninstall unused tools

卸载不再使用的工具

uv tool uninstall old-tool

Check what's installed

查看已安装的工具

uv tool list

Free up disk space

释放磁盘空间

uv cache prune

undefined

uv cache prune

undefined

Step 7: Handle Tool Dependencies and Conflicts

步骤7：处理工具依赖与冲突

Tools with conflicting dependencies:

bash

undefined

存在依赖冲突的工具：

bash

undefined

These tools both depend on different versions of a library

这些工具依赖同一库的不同版本

uvx creates isolated environments, avoiding conflicts

uvx会创建隔离环境，避免冲突

uvx tool-a uvx tool-b

Both run in separate, isolated environments

两者在独立的隔离环境中运行

No dependency conflicts

无依赖冲突


**Tools requiring additional packages:**
```bash


**需要额外包的工具：**
```bash

Add extra packages to tool execution

在执行工具时添加额外包

uvx --with mkdocs-material mkdocs serve

Tool runs with mkdocs + mkdocs-material installed

工具会在安装了mkdocs + mkdocs-material的环境中运行


**Specific Python version for tool:**
```bash


**需要特定Python版本的工具：**
```bash

Some tools require specific Python versions

部分工具需要特定Python版本

Ensure compatibility

确保兼容性

uvx --python 3.9 older-tool

Run with minimum supported Python

使用最低支持的Python版本运行

uvx --python 3.10 modern-tool

undefined

uvx --python 3.10 modern-tool

undefined

Examples

示例

Example 1: One-Time Tool Usage (uvx)

示例1：一次性工具使用（uvx）

You need to check code quality but don't use ruff regularly:

bash

undefined

你需要检查代码质量，但不经常使用ruff：

bash

undefined

Run ruff once to check your code

运行ruff一次性检查代码

uvx ruff check .

Output analysis but don't install anything

输出分析结果，但不会安装任何内容

After execution, no system changes

执行后，系统无任何变更

Next time you run it, it's fetched again (but cached locally)

下次运行时会再次拉取（但会在本地缓存）

undefined

undefined

Example 2: Regular Linting in Project (uv run)

示例2：项目中定期代码检查（uv run）

Your project uses ruff as a dev dependency:

bash

undefined

你的项目将ruff作为开发依赖：

bash

undefined

In your project directory

进入项目目录

cd my-project

Edit pyproject.toml to add ruff to dev dependencies

编辑pyproject.toml，将ruff添加到开发依赖

[dependency-groups]

lint = ["ruff>=0.1.0"]

Sync environment

同步环境

uv sync --group lint

Run linter from project environment

从项目环境中运行代码检查工具

uv run ruff check .

Everyone on team uses same ruff version (from uv.lock)

团队所有成员使用相同版本的ruff（来自uv.lock）

undefined

undefined

Example 3: Global Tool Installation (uv tool install)

示例3：全局工具安装（uv tool install）

You use ruff across multiple projects:

bash

undefined

你在多个项目中使用ruff：

bash

undefined

Install once globally

一次性全局安装

uv tool install ruff

Use in any directory

在任意目录中使用

cd project-a && ruff check . cd ../project-b && ruff check .

No project setup needed

无需项目配置

Tool always available in PATH

工具始终在PATH中可用

undefined

undefined

Example 4: Test Different Python Versions

示例4：测试不同Python版本

You need to verify code works on Python 3.10 and 3.12:

bash

undefined

你需要验证代码在Python 3.10和3.12上均可运行：

bash

undefined

Run with Python 3.10

使用Python 3.10运行

uvx --python 3.10 pytest tests/

Run with Python 3.12

使用Python 3.12运行

uvx --python 3.12 pytest tests/

Each uses different Python version

两者使用不同的Python版本

No installation overhead

无安装开销

undefined

undefined

Example 5: Tool with Extras

示例5：带可选依赖的工具

mypy runs faster with optional faster-cache feature:

bash

undefined

启用快速缓存的mypy运行速度更快：

bash

undefined

Via uvx (temporary)

通过uvx临时使用

uvx --from 'mypy[faster-cache]' mypy src/

Via uv tool install (persistent)

通过uv tool install持久化安装

uv tool install 'mypy[faster-cache]' mypy src/

undefined

uv tool install 'mypy[faster-cache]' mypy src/

undefined

Example 6: CI/CD Pipeline

示例6：CI/CD流水线

Your CI uses different tools without installation:

bash

undefined

你的CI流程无需安装即可使用不同工具：

bash

undefined

.github/workflows/ci.yml

name: Lint code run: uvx ruff check .
name: Type check run: uvx mypy src/
name: Format check run: uvx black --check .
name: Test run: | uv sync --group test uv run pytest tests/


Each step is clean, isolated, no tool installation overhead.

name: 代码检查 run: uvx ruff check .
name: 类型检查 run: uvx mypy src/
name: 格式检查 run: uvx black --check .
name: 测试 run: | uv sync --group test uv run pytest tests/


每个步骤都简洁、隔离，无工具安装开销。

Example 7: Cleanup and Maintenance

要求

Remove old tools and free disk space:

bash

undefined

已安装uv（安装方式：

curl -LsSf https://astral.sh/uv/install.sh | sh

）

已安装Python 3.8+（用于运行工具）
了解项目的依赖结构

See what's installed

Remove tool you no longer use

—

uv tool uninstall old-formatter

—

Prune cache of unused packages

—

uv cache prune

—

Check cache location and size

—

uv cache dir

undefined

—

Requirements

—

uv installed (install via:

curl -LsSf https://astral.sh/uv/install.sh | sh

)

Python 3.8+ available (for running tools)
Understanding of your project's dependency structure

—

uv-tool-management

Original

Translation

uv Tool Management

uv 工具管理

Purpose

用途

Quick Start

快速开始

Run ruff (Python linter) once without installation

无需安装，一次性运行ruff（Python代码检查工具）

Equivalent longer form

等效的完整写法

Install a tool permanently for repeated use

持久化安装工具以重复使用

Then run the installed tool

运行已安装的工具

Instructions

操作指南

Step 1: Understand the Tool Management Landscape

步骤1：了解工具管理场景

Step 2: Choose Between uvx and uv tool install

步骤2：选择uvx与uv tool install的使用场景

Try a new tool without committing to it

试用新工具，无需长期安装

Run a tool on-demand in CI

在CI中按需运行工具

Run tool from different package

运行来自不同包的工具

Install tools you use daily

安装日常使用的工具

Then run directly without prefix

直接运行，无需前缀

Test runner needs access to project (test libraries, modules)

测试运行器需要访问项目资源（测试库、模块）

Linter running on project code

对项目代码进行类型检查

Format project code

格式化项目代码

Step 3: Run Tools with uvx

步骤3：使用uvx运行工具

Run specific version of a tool

运行工具的特定版本

Use version constraint

使用版本约束

httpie is in package 'httpie', command is 'http'

httpie属于包'httpie'，命令为'http'

mkdocs is in 'mkdocs', command is 'mkdocs'

mkdocs属于包'mkdocs'，命令为'mkdocs'

mypy with optional faster caching

启用了快速缓存可选依赖的mypy

mkdocs with material theme

搭配mkdocs-material主题的mkdocs

Run tool with Python 3.10 (useful for compatibility testing)

使用Python 3.10运行工具（适用于兼容性测试）

Ensure tool runs on minimum supported version

使用最低支持版本运行工具

Install directly from GitHub

直接从GitHub安装并运行

Step 4: Install and Manage Persistent Tools

步骤4：安装与管理持久化工具

Install latest version

安装最新版本

Install specific version

安装特定版本

Install with extras

安装包含可选依赖的工具

Install from git

从Git仓库安装

Example output:

示例输出：

black 0.23.11 /Users/user/.local/bin/black

black 0.23.11 /Users/user/.local/bin/black

mypy 1.7.0 /Users/user/.local/bin/mypy

mypy 1.7.0 /Users/user/.local/bin/mypy

ruff 0.3.0 /Users/user/.local/bin/ruff

ruff 0.3.0 /Users/user/.local/bin/ruff

Upgrade specific tool to latest

将特定工具升级到最新版本

Upgrade all tools