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 文件，无需引入新的配置文件格式：

ini 复制代码

[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 速度优势的场景。

bash 复制代码

# 创建虚拟环境
uv venv

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # 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 工作流的场景。

csharp 复制代码

# 初始化 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：混合使用

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

bash 复制代码

# 使用 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。

与其他工具的对比

工具	用途	安装	速度	环境隔离
`pip install`	安装到当前环境	持久	慢	❌
`pipx`	隔离安装 CLI 工具	持久	中等	✅
`uvx`	临时运行工具	缓存	极快	✅

核心使用场景

1. 代码格式化和检查

bash 复制代码

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

# 代码检查
uvx ruff check .

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

# 类型检查
uvx mypy src/

2. 运行测试工具

ini 复制代码

# 运行 pytest
uvx pytest tests/

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

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

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

bash 复制代码

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

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

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

4. 数据处理工具

bash 复制代码

# CSV 处理
uvx csvkit data.csv

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

uvx 的高级用法

指定工具版本

ini 复制代码

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

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

运行需要额外依赖的脚本

csharp 复制代码

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

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

从 Git 仓库运行

csharp 复制代码

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

uvx 的工作原理

当你运行 uvx tool_name 时：

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

这种机制确保了：

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

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

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

uvx：运行外部工具

bash 复制代码

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

使用场景：

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

uv run：运行项目脚本

arduino 复制代码

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

使用场景：

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

五、实际工作流推荐

新项目工作流

csharp 复制代码

# 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 迁移的工作流

csharp 复制代码

# 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 工作流

yaml 复制代码

# .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. 统一工具链

一个工具完成多个任务：

csharp 复制代码

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 项目怎么办？

答：有三个选择：

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

Q3: uvx 的缓存在哪里？

答： uvx 的缓存通常在：

Linux/Mac: ~/.cache/uv/
Windows: %LOCALAPPDATA%\uv\cache

可以用 uv cache clean 清理。

Q4: uv 支持私有 PyPI 源吗？

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

lua 复制代码

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

或通过环境变量：

ini 复制代码

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

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

答：建议：

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

八、总结

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

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

无论你是：

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

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

参考资源

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