技术分享

我是如何使用Python包管理工具uv的

1. 什么是 uv？

uv 是一个用 Rust 编写的极速 Python 包管理器，它旨在替代 pip、pip-tools、poetry、pdm 等传统工具。uv 的主要特点包括：

  • ⚡ 极速: 比传统工具快 10-100 倍
  • 🔒 可靠: 确定性依赖解析
  • 🛠️ 功能完整: 支持虚拟环境、依赖管理、项目构建等
  • 🐍 兼容性: 完全兼容 pip 生态系统

2. 安装 uv

2.1 通过独立的安装程序安装

macOS/Linux

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

Windows

1
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2.2 使用 pip 安装

1
pip install uv

3. 基本使用

3.1 创建新项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 创建新的 Python 项目
uv init my-project
cd my-project

# 或者指定项目名称
uv init --name my-project

# 初始化时指定 Python 版本
uv init --python 3.11

# 初始化并创建虚拟环境
uv init --venv

# 在现有目录中初始化 uv 项目
cd my-project
uv init

3.2 安装依赖

1
2
3
4
5
6
7
8
# 安装单个包
uv add requests

# 安装开发依赖
uv add --dev pytest

# 从 requirements.txt 安装
uv pip install -r requirements.txt

3.3 运行命令

1
2
3
4
5
6
7
8
9
# 运行 Python 脚本
uv run script.py

# 运行测试
uv run pytest

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

3.4 克隆 GitHub 项目后使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 克隆项目
git clone https://github.com/user/repo.git
cd repo

# 检查项目是否有 pyproject.toml
ls -la | grep pyproject.toml

# 使用 uv sync 安装所有依赖（推荐）
uv sync

# 如果项目需要特定Python版本
uv sync --python 3.11

# 运行项目
uv run python main.py
uv run pytest

3.5 管理依赖

1
2
3
4
5
6
7
8
# 查看已安装的包
uv pip list

# 更新依赖
uv lock --upgrade

# 移除包
uv remove package-name

4. 项目配置

4.1 pyproject.toml 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[project]
name = "my-project"
version = "0.1.0"
description = "A sample project using uv"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.25.0",
    "pandas>=1.3.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=6.0",
    "black>=21.0",
    "flake8>=3.8",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

5. 迁移指南

5.1 从 pip + venv + requirements.txt 迁移

如果你之前使用传统的 pip + venv + requirements.txt 方式管理依赖，可以按以下步骤迁移到 uv：

第一步：导出当前环境的依赖

1
2
3
4
5
6
# 激活现有虚拟环境
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows

# 导出依赖列表
pip freeze > requirements.txt

第二步：使用 uv 重新创建项目环境

1
2
3
4
5
6
7
8
9
10
11
# 在项目根目录初始化 uv 项目
uv init

# 创建新的虚拟环境
uv venv

# 安装依赖（uv 会自动使用 .venv 目录）
uv pip install -r requirements.txt

# 生成 uv.lock 文件
uv lock

第三步：更新项目配置

1
2
# 将依赖添加到 pyproject.toml（可选，但推荐）
uv add $(cat requirements.txt | grep -v '^$' | tr '\n' ' ')

第四步：验证迁移

1
2
# 运行项目确保一切正常
uv run python your_script.py

5.2 从 Poetry 迁移

如果你之前使用 Poetry 管理项目，可以按以下步骤迁移到 uv：

第一步：导出 Poetry 依赖

1
2
3
4
5
# 导出为 requirements.txt 格式
poetry export -f requirements.txt --output requirements.txt --without-hashes

# 或者导出开发依赖
poetry export -f requirements.txt --output requirements-dev.txt --dev --without-hashes

第二步：使用 uv 重新创建项目

1
2
3
4
5
6
7
8
9
10
11
# 初始化 uv 项目
uv init

# 安装生产依赖
uv pip install -r requirements.txt

# 安装开发依赖（如果有）
uv pip install -r requirements-dev.txt

# 生成锁文件
uv lock

第三步：清理旧文件

1
2
3
4
5
# 删除 Poetry 相关文件
rm pyproject.toml  # 注意：这会删除原有的 pyproject.toml
rm poetry.lock

# uv init 会创建新的 pyproject.toml

第四步：验证迁移

1
2
3
# 确保项目正常运行
uv run python -m your_module
uv run pytest

6. 我的使用体验

6.1 优势

  1. 速度惊人: 安装包的速度比 pip 快很多
  2. 依赖解析稳定: 不会出现依赖冲突问题
  3. 工具链完整: 一个工具解决所有包管理需求
  4. 现代化: 支持最新的 Python 包管理标准

6.2 注意事项

  1. 学习曲线: 需要适应新的命令和概念
  2. 生态系统: 某些高级功能可能还在开发中
  3. 团队协作: 需要确保团队成员都使用相同的工具

7. 总结

uv 是一个非常有前景的 Python 包管理工具，它的速度和可靠性让我在日常开发中受益匪浅。虽然还在快速发展中，但已经可以满足大部分使用场景。

如果你还没有尝试过 uv，我强烈建议你试试看！

参考链接: