uv 完全指南：Python 包管理的现代化解决方案

引言

uv 是一个用 Rust 编写的超快速 Python 包管理器，由 Astral 团队（ruff 的创建者）开发。它不仅可以替代 pip、pipx，还能与现有的 Poetry 项目无缝集成。本文将全面介绍 uv 的核心功能和实际使用场景。

一、uv 与 pyproject.toml 的集成

理解配置文件

首先需要明确几个容易混淆的概念：

• pyproject.toml - Python 项目的标准配置文件，定义项目元数据和依赖
• poetry.toml - Poetry 工具自身的配置文件（如虚拟环境位置等）

重要： uv 可以直接读取 pyproject.toml，但不会使用 poetry.toml。

uv 的原生兼容性

uv 原生支持读取 pyproject.toml 文件，无需引入新的配置文件格式：

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.0"
pandas = "^2.0.0"

[tool.poetry.dev-dependencies]
pytest = "^7.0.0"

uv 可以直接读取上面的依赖声明并进行安装。

二、uv 与 Poetry 项目的三种集成方式

方式 1：保留 Poetry 格式，使用 uv 安装

这种方式适合想要保持现有 Poetry 项目结构，但希望享受 uv 速度优势的场景。

# 创建虚拟环境
uv venv

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
# 或 .venvScriptsactivate  # Windows

# 使用 uv 安装项目依赖
uv pip install -e .

# 或从 poetry.lock 导出后安装
poetry export -f requirements.txt -o requirements.txt
uv pip install -r requirements.txt

优点：

• 保留完整的 Poetry 生态
• 利用 uv 的安装速度
• 团队成员可以选择使用 Poetry 或 uv

方式 2：完全迁移到 uv

适合新项目或希望完全采用 uv 工作流的场景。

# 初始化 uv 项目（会读取现有的 pyproject.toml）
uv init

# 同步依赖
uv sync

# 添加新依赖
uv add requests

# 添加开发依赖
uv add --dev pytest

# 运行脚本
uv run python script.py

注意事项：

• uv 会生成 uv.lock 文件替代 poetry.lock
• 可以删除 poetry.lock 和 poetry.toml
• pyproject.toml 保留，这是 Python 标准

方式 3：混合使用

在过渡期间，可以同时使用两者的优势。

# 使用 Poetry 管理依赖
poetry add pandas

# 使用 uv 进行快速安装
poetry export -f requirements.txt -o requirements.txt
uv pip sync requirements.txt

# 使用 uv 运行脚本（更快）
uv run python main.py

三、uvx：一次性运行工具的利器

什么是 uvx？

uvx 是 uv 提供的命令，用于临时运行 Python 命令行工具，无需安装到全局环境。这类似于 Node.js 的 npx 或 Python 的 pipx。

与其他工具的对比

核心使用场景

1. 代码格式化和检查

# 格式化代码（无需安装 black）
uvx black my_code.py

# 代码检查
uvx ruff check .

# 自动修复
uvx ruff check . --fix

# 类型检查
uvx mypy src/

2. 运行测试工具

# 运行 pytest
uvx pytest tests/

# 带详细输出
uvx pytest tests/ -v

# 运行覆盖率测试
uvx pytest --cov=src tests/

3. 一次性使用的实用工具

# HTTP 客户端
uvx httpie GET https://api.github.com

# 有趣的命令行工具
uvx cowsay "Hello from uvx!"

# 启动简单的 HTTP 服务器
uvx http.server 8000

4. 数据处理工具

# CSV 处理
uvx csvkit data.csv

# JSON 处理
uvx jq '.data' response.json

uvx 的高级用法

指定工具版本

# 使用特定版本的工具
uvx black==23.0.0 file.py

# 指定 Python 版本
uvx --python 3.11 black .

运行需要额外依赖的脚本

# script.py 需要 requests 库
uvx --with requests python script.py

# 多个依赖
uvx --with requests --with pandas python data_script.py

从 Git 仓库运行

# 从 GitHub 运行脚本
uvx --from git+https://github.com/user/repo script.py

uvx 的工作原理

当你运行 uvx tool_name 时：

1. uv 检查本地缓存中是否有该工具
2. 如果没有，快速下载并创建临时隔离环境
3. 在隔离环境中运行工具
4. 缓存环境供下次使用（但不影响全局环境）

这种机制确保了：

• 环境干净，不会污染全局
• 重复使用时速度极快（利用缓存）
• 不同工具完全隔离
• 可以同时使用同一工具的不同版本

四、uvx vs uv run：选择正确的命令

理解这两个命令的区别很重要：

uvx：运行外部工具

# 运行已发布到 PyPI 的包/工具
uvx black .
uvx ruff check .
uvx httpie https://api.example.com

使用场景：

• 一次性使用的工具
• 不属于项目依赖的命令行工具
• 测试或尝试新工具

uv run：运行项目脚本

# 运行项目中的脚本（使用项目依赖环境）
uv run python my_script.py
uv run pytest
uv run python -m mypackage

使用场景：

• 运行项目代码
• 使用项目依赖
• 开发过程中的日常命令

五、实际工作流推荐

新项目工作流

# 1. 创建项目
uv init my-project
cd my-project

# 2. 添加依赖
uv add fastapi uvicorn
uv add --dev pytest black ruff

# 3. 开发过程
uv run python main.py

# 4. 代码质量检查（使用 uvx）
uvx black .
uvx ruff check .

# 5. 运行测试
uv run pytest

从 Poetry 迁移的工作流

# 1. 保留 pyproject.toml，初始化 uv
uv init

# 2. 同步现有依赖
uv sync

# 3. 后续添加依赖使用 uv
uv add new-package

# 4. 可以删除 poetry.lock 和 poetry.toml
rm poetry.lock poetry.toml

# 5. 开发流程
uv run python app.py
uvx black .  # 格式化
uvx ruff check .  # 检查

CI/CD 工作流

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
      
      - name: Install dependencies
        run: uv sync
      
      - name: Run tests
        run: uv run pytest
      
      - name: Check code quality
        run: |
          uvx black --check .
          uvx ruff check .

六、uv 的核心优势

1. 速度优势

uv 用 Rust 编写，比传统的 pip 快 10-100 倍：

• 依赖解析：并行处理，智能缓存
• 下载速度：并发下载多个包
• 安装速度：优化的安装算法

2. 统一工具链

一个工具完成多个任务：

uv venv           # 创建虚拟环境
uv pip install    # 安装包
uv add            # 添加依赖
uv run            # 运行脚本
uvx               # 临时运行工具

3. 向后兼容

• 完全兼容 pip 命令
• 支持 requirements.txt
• 支持 pyproject.toml
• 可与 Poetry 项目集成

4. 现代化特性

• 自动虚拟环境管理
• 智能依赖锁定
• 并行操作
• 详细的错误信息

七、常见问题解答

Q1: uv 能完全替代 Poetry 吗？

答： 可以。uv 提供了依赖管理、虚拟环境、构建等核心功能。如果你只需要这些功能，完全可以迁移到 uv。

Q2: 已有的 Poetry 项目怎么办？

答： 有三个选择：

1. 保留 Poetry，用 uv 加速安装
2. 完全迁移到 uv（保留 pyproject.toml）
3. 混合使用，逐步过渡

Q3: uvx 的缓存在哪里？

答： uvx 的缓存通常在：

• Linux/Mac: ~/.cache/uv/
• Windows: %LOCALAPPDATA%uvcache

可以用 uv cache clean 清理。

Q4: uv 支持私有 PyPI 源吗？

答： 支持。可以在 pyproject.toml 中配置：

[[tool.uv.index]]
url = "https://pypi.example.com/simple"

或通过环境变量：

export UV_INDEX_URL="https://pypi.example.com/simple"

Q5: 团队协作时如何统一？

答： 建议：

1. 提交 uv.lock 到版本控制
2. 在 CI/CD 中使用 uv sync 确保环境一致
3. 在 README 中说明使用 uv

八、总结

uv 代表了 Python 包管理的新方向：

• 极致性能：Rust 实现，速度提升 10-100 倍
• 无缝集成：兼容现有工具和格式
• 简化工作流：一个工具多种用途
• 开发体验：uvx 让临时工具使用变得轻松

无论你是：

• 开始新项目 → 直接使用 uv
• 维护 Poetry 项目 → 可以逐步集成
• 需要临时工具 → uvx 是最佳选择

Python 包管理正在变得更快、更简单、更现代化。uv 值得你尝试！

参考资源

• uv 官方文档
• uv GitHub 仓库
• Python Packaging 指南

本文最后更新时间：2025年10月