Gradio全解14——使用Gradio构建MCP的服务器与客户端（4）——Python包命令：uv与uvx实战

14.4 Python包命令：uv与uvx实战

pip是最常用的Python包管理工具，但现在出现了一个速度更快，功能更全面强大，而且被广泛用在AI MCP管理中的包工具，那就是uv。而uvx是uv的包执行命令，下面将分别讲解并实战。

14.4.1 uv核心亮点与常用命令

本节介绍uv核心亮点，并实战其常用命令，包括安装、项目管理、脚本、工具、Python版本与pip接口等。

1. uv：Python包极速管理器

uv是一款由Rust打造的Python包和工程极速管理器，是拥有虚拟环境管理、依赖管理、Python版本管理、脚本运行、打包发布等多种功能的Python一体化工具链，可以说集齐了venv、virtualenv、pip、poetry等能力于一身，uv官方文档🖇️[链接14-8]。据说uv对于包的解析安装速度比pip快数十倍，配置虚拟环境的速度也比virtualenv快数十倍，各类工具的平均执行速度对比如图14-7所示：

图14-7

UV核心亮点有：

• 🚀 可以替代pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv等一众工具的单一工具。
• ⚡️ 性能提升：比pip快10至100倍。
• 🗂️️ 通过通用锁文件机制实现全能项目管理。
• ❇️ 脚本执行，支持内联的依赖元数据。
• 🐍 支持安装与控制Python版本。
• 🛠️ 支持运行和安装Python包形式的工具。
• 🔩 有兼容pip的接口，在熟悉的CLI中操作的同时提高性能。
• 🏢 支持工程可扩展的Cargo式工作区。
• 💾 磁盘空间效率高，支持依赖关系去重的全局缓存。
• ⏬ 可通过curl或pip安装，安装时无需Rust或Python。
• 🖥️ 跨平台支持：macOS、Linux和Windows。

uv由Astral（Ruff之父）提供支持，Ruff是一款基于Rust编写的极速Python静态检查器与代码格式化工具。下面将以Ruff为例，分别介绍UV的常用命令。

2. 安装与项目管理

使用官方独立安装程序安装uv：

# macOS、Linux平台
> curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

也可直接用pip/pipx安装：

> pip/pipx install uv

uv也可以使用Cargo、Homebrew、WinGet、Scoop、Docker等安装，并可指定版本，详细信息请参阅官方文档的安装部分。

uv可以管理虚拟环境、项目与依赖，支持锁文件、工作区等特性，功能类似rye或poetry。以简单创建虚拟环境、初始化项目并添加依赖为例，代码及注释如下所示：

# 在当前目录下创建一个名为my-project-env的虚拟环境，使用指定的Python 3.13版本。如未命名，则在当前目录下创建一个名为.venv的虚拟环境
> uv venv -p python3.13 my-project-env
# 激活虚拟环境
# Windows (CMD): .\venv\Scripts\activate
# macOS/Linux (Bash/Zsh): source venv/bin/activate
# 然后初始化项目
> uv init example-uv
Initialized project `example-uv` at `D:\mcp\example_uv`
# 在项目中添加依赖
> cd example-uv
> uv add ruff
Resolved 2 packages in 1m 29s
Prepared 1 package in 2m 03s
Installed 1 package in 28ms+ ruff==0.12.0
# 使用ruff检查项目文件
> uv run ruff check
All checks passed!

uv支持构建及发布项目——即使该项目未使用uv管理。锁文件、工作区及其他主要的项目与依赖命令有：

• uv lock：生成锁文件。
• uv sync：同步依赖到虚拟环境。
• uv remove：移除依赖。
• uv tree：查看依赖列表。
• uv build：生成发布包。
• uv publish：发布到PyPI（Python Package Index）。

更多项目管理命令用法请参阅官方文档：uv - Projects🖇️[链接14-9]。

3. 管理脚本与执行工具

uv支持管理单文件脚本的虚拟环境与依赖。创建新脚本时，可通过内联元数据声明依赖项：

> echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
> uv add --script example.py requests
Updated `example.py`
# 随后可在隔离的虚拟环境中运行脚本
> uv run example.py
Installed 5 packages in 46ms

文件example.py的内容如下：

# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "requests",
# ]
# ///
'import requests; print(requests.get("https://astral.sh"))' 

uv可以执行并安装由Python包提供的命令行工具，类似于pipx。下面通过示例说明。
首先，使用uvx（即uv tool run的别名）在临时环境中运行工具：

> uvx pycowsay 'hello world!'
Installed 1 package in 60ms--------------
< 'hello world!' >--------------\   ^__^\  (oo)\_______(__)\       )\/\||----w |||     ||

然后，使用uv tool install可安装工具：

> uv tool install ruff
Resolved 1 package in 9.31s
Installed 1 package in 54ms+ ruff==0.12.0
Installed 1 executable: ruff.exe

4. 管理Python版本与uv pip命令

uv支持快速安装Python并管理版本，比如：

# 安装多个Python版本
> uv python install 3.11 3.12 3.13
# 按需下载Python版本：
> uv venv --python 3.12.0
> uv run --python pypy@3.8 -- python
# 在当前目录固定为使用特定Python版本：
> uv python pin 3.11
Pinned `.python-version` to `3.11`

在特定版本上运行工具，可以使用command@<version>。其他主要方法有：uv python list：查看安装的Python版本。uv python uninstall：卸载某版本Python。

pip接口：uv提供了对常见pip、pip-tools和virtualenv命令的直接替代方案，uv通过高级功能扩展了它们的接口，例如覆盖依赖版本、跨平台解析、可重现解析、可替代解析策略等。uv pip命令是移植了pip的接口，能实现pip的所有功能并进行优化，语法一致且速度更快，体验更好。我们无需更改现有工作流即可迁移到uv，并可体验10-100倍的速度提升。

例如，将requirements.in文件中依赖项编译生成精确的跨平台的requirements.txt文件以锁定依赖：

> uv pip compile requirements.in --universal --output-file requirements.txt

安装锁文件：

> uv pip sync docs/requirements.txt

最后删除当前目录下的名为.venv的虚拟环境：

> rmdir /s /q .venv

uv pip其他主要的包管理方法有：

• uv pip list：列出激活环境中已安装的包。
• uv pip show：显示已安装包的细节。
• uv pip freeze：显示已安装包列表及其版本号。
• uv pip check：检查当前环境是否有兼容的包。
• uv pip uninstall：卸载包。
• uv pip tree：查看环境依赖。
• uv pip sync：同步依赖。

这些操作涵盖了使用uv进行Python项目开发和依赖管理的常见需求。总的来说，uv基本能实现venv、virtualenv、pip、poetry的所有功能，而且速度更快，功能更多，能减少工具切换的时间成本，可能会成为Python环境管理的首选工具。

14.4.2 uvx工具执行指令解析

uvx是Python包管理工具uv的重要组成部分，主要用于在隔离环境中快速运行Python命令行工具或脚本而无需永久安装工具包。下面详细解析其核心功能和使用场景。

1. uvx的命令选项与隔离特性

uvx是工具执行器的角色，它是uv tool run的别名，前文已分别举例。uvx类似于pipx或npx，但性能更高，例如：

uvx ruff@latest check .  # 自动下载Ruff并执行代码检查

另外，命令选项--from可用于从特定包中调用命令，同时可以指定版本，还可用于运行带有额外功能的工具，示例如下：

uvx --from 'ruff==0.3.0' ruff check
uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

还可以使用--with选项包含其他依赖项，例如在运行mkdocs时包含mkdocs-material包：

uvx --with mkdocs-material mkdocs --help

更多命令选项请参阅：uv - Using Tools🖇️[链接14-10]。

uvx会创建临时环境以实现隔离。uvx在后台自动创建临时虚拟环境，直接运行以Python包形式发布的命令行工具（如代码检查工具Ruff、格式化工具Black等），而无需显式安装到本地环境。工具运行结束后环境会被清理，确保不会污染当前项目或系统环境。这种方式避免了全局安装工具可能导致的依赖冲突，同时减少了磁盘空间的占用。这一隔离特性特别适合偶尔使用的工具或需要严格环境隔离的场景。此外，uvx还具有性能优势，由于uv基于Rust实现，uvx的工具安装和运行速度远超传统工具（如pipx）。

2. uvx的典型应用场景

uvx的典型应用场景包括下面三种：

1. 单次脚本或工具执行。对于只需临时使用无需安装的工具，如生成文档工具sphinx或数据分析工具pandas-profiling，可直接通过uvx运行：

uvx pandas-profiling data.csv # 生成数据分析报告后自动清理环境

2. CI/CD流程优化。在持续集成(Continuous Integration)和持续部署(Continuous Deployment)环境中，通过uvx隔离运行测试或代码检查工具，既能减少构建时间，又能避免工具版本冲突。例如：

uvx pytest tests/  # 在隔离环境中运行测试

3. 跨团队协作。当项目成员需要统一工具链版本时，通过uvx运行指定版本的命令行工具，确保结果一致性。例如：

uvx black==23.12.0 --check .  # 使用固定版本的代码格式化工具

3. uvx与传统工具对比及其技术特点

uvx与传统工具pipx、npx相比如何呢？三者功能定位、性能、环境隔离性及使用场景对比见表14-1：

表14-1

工具	功能定位	性能	环境隔离性	适用场景
pipx	全局CLI工具安装与管理	慢	高	需要重复使用的工具
npx	Node.js工具临时执行	中	高	Node生态的一次性工具运行
uvx	Python工具临时执行	快	高	高性能需求、严格隔离的场景

uvx的技术实现特点主要有以下三方面：

1. 依赖全局缓存。uvx利用uv的全局包缓存机制，重复使用的工具包无需重复下载，进一步加速执行速度。
2. 兼容PEP 723🖇️[链接14-11]，它是内联脚本元数据的语法规范。对于单文件脚本，uvx支持通过内联元数据（如# dependencies = ["requests"]）自动解析依赖，并通过uv run直接运行。如果脚本依赖于第三方库，可以在文件顶部的格式化的注释中声明这些依赖。
3. 跨平台支持。uvx支持macOS、Linux和Windows，且在不同平台下的行为一致，确保开发流程的跨平台兼容性。

总结：uvx是uv工具链中的高效执行模块，通过临时环境隔离和极速依赖管理，重新定义了Python命令行工具的使用方式。其设计理念与Rust生态的Cargo工具一脉相承，是追求效率与安全的开发者值得尝试的新一代解决方案。