Python包管理工具之uv的使用详细指南

uv：新一代高性能 Python 包管理工具指南

一、uv 简介

uv 是由 Astral 公司（Ruff 的创建者）开发的用 Rust 编写的超快速 Python 包管理器和解析器，旨在替代 pip、pip-tools、virtualenv、pipenv、poetry 等工具。

主要优势：

• ⚡ 速度极快：比传统工具快 10-100 倍
• 🚀 一体化工具：包管理 + 虚拟环境 + 依赖解析
• 📦 兼容性强：支持 pip、pip-tools、poetry 的工作流
• 🔧 现代化设计：内置虚拟环境、快速依赖解析、并行下载

二、安装 uv

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

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 使用 pip（如果需要）
pip install uv

uv --version
# 输出示例：uv 0.1.0 (Rust 1.75.0)

三、核心功能与使用

# 创建新项目目录
mkdir myproject && cd myproject

# 初始化 pyproject.toml（类似 poetry）
uv init
# 或手动创建项目结构

添加依赖：

# 添加单个包（默认到 main 依赖组）
uv add requests

# 添加指定版本的包
uv add "flask>=2.0,<3.0"

# 添加到开发依赖组
uv add --dev pytest black mypy

# 添加多个包
uv add pandas numpy matplotlib

查看依赖：

# 查看已安装的包
uv pip list

# 查看依赖树
uv tree

更新依赖：

# 更新所有包到最新兼容版本
uv update

# 更新指定包
uv update requests pandas

# 更新到指定版本
uv add "django==4.2.0"

移除依赖：

uv remove requests

自动虚拟环境（默认）：

# uv 会自动创建和管理 .venv
uv add requests  # 自动使用 .venv

手动指定虚拟环境：

# 创建新虚拟环境
uv venv .venv

# 使用现有虚拟环境
uv sync --python 3.11

激活虚拟环境：

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

从 pyproject.toml 安装：

# 安装所有依赖（包括开发依赖）
uv sync

# 仅安装生产依赖
uv sync --no-dev

# 安装并生成锁文件
uv sync --locked

从 requirements.txt 安装：

# 安装 requirements.txt 中的依赖
uv pip install -r requirements.txt

# 生成 requirements.txt
uv pip compile pyproject.toml -o requirements.txt

# 使用特定 Python 版本
uv sync --python 3.11
uv sync --python 3.12

# 查看支持的 Python 版本
uv python list

# 安装特定 Python 版本
uv python install 3.12

四、项目配置示例

[project]
name = "myproject"
version = "0.1.0"
description = "My awesome project"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
    "pandas>=1.5.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "mypy>=1.0.0",
    "ruff>=0.1.0",
]
docs = [
    "sphinx>=6.0.0",
    "mkdocs>=1.4.0",
]

[tool.uv]
# uv 特定配置（可选）

# 生成锁文件
uv lock

# 使用锁文件安装（确保一致性）
uv sync --locked

五、工作流示例

# 1. 创建项目
mkdir new-project && cd new-project
uv init

# 2. 添加依赖
uv add fastapi "pydantic>=2.0.0"
uv add --dev pytest ruff

# 3. 安装所有依赖
uv sync

# 4. 激活环境
source .venv/bin/activate

# 5. 运行代码
uv run python main.py

# 从 requirements.txt 迁移
uv pip compile requirements.txt -o pyproject.toml

# 或从 poetry 迁移
# 保持 pyproject.toml，直接使用 uv 管理
uv sync

# GitHub Actions 示例
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v1
        with:
          python-version: "3.11"
      - run: uv sync --dev
      - run: uv run pytest

六、高级功能

# 从 Git 仓库安装
uv add "git+https://github.com/user/repo.git"

# 从本地路径安装
uv add ./path/to/package

# 设置镜像源
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
export UV_EXTRA_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"

# 或使用配置文件
# ~/.config/uv/config.toml
[install]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

# 安装特定组的依赖
uv sync --group docs
uv sync --group dev

# 创建离线包缓存
uv pip download -d ./packages -r requirements.txt

# 离线安装
uv pip install --no-index --find-links ./packages -r requirements.txt

七、常用命令速查

八、最佳实践建议

版本控制：

• 将 pyproject.toml 和 uv.lock 提交到版本控制
• 忽略 .venv 目录

依赖管理：

# 使用精确版本范围
uv add "package>=1.0,<2.0"

# 定期更新依赖
uv update --dry-run  # 先查看更新
uv update  # 执行更新

性能优化：

# 并行安装（默认启用）
uv sync --no-cache  # 禁用缓存（测试用）

# 使用系统 Python（更快）
uv sync --system

多环境配置：

# pyproject.toml
[tool.uv.python]
version = "3.11"

[tool.uv.dev-dependencies]
test = ["pytest", "pytest-cov"]
lint = ["ruff", "black"]
type = ["mypy", "types-requests"]

九、故障排除

清理缓存：

uv cache clean

调试模式：

UV_LOG=debug uv sync

解决依赖冲突：

# 查看依赖解析问题
uv tree --all

# 使用 pip 兼容模式
uv pip install --resolution=backtracking

十、从其他工具迁移

uv 通过其卓越的性能和一体化设计，正在成为 Python 包管理的新标准。它特别适合需要快速迭代的现代开发工作流和 CI/CD 环境。