uv — 极速 Python 包管理器¶

一句话说明： uv 是 Astral 公司用 Rust 编写的 Python 包管理器，速度比 pip 快 10-100 倍，统一了虚拟环境、依赖管理和 Python 版本管理。

核心知识点速查表¶

知识点	说明
为什么要学	见对应章节
核心概念详解	见对应章节
安装与配置	见对应章节
快速上手	见对应章节
进阶用法	见对应章节
常见问题与排错	见对应章节
面试高频考点	见对应章节
参考资源	见对应章节

为什么要学¶

面试加分 — 展示你了解 Python 包管理的痛点和现代解决方案
实用性 — 安装依赖从分钟级降到秒级，CI/CD 提速显著
统一工具 — 替代 pip + virtualenv + pyenv + pip-tools 的组合
工程规范 — 支持 lockfile，确保团队环境一致

核心概念详解¶

为什么 pip 慢？¶

白话： pip 用 Python 写，解析依赖是串行的，每次都要重新计算。uv 用 Rust 写，并行解析 + 全局缓存，所以快得离谱。

对比项	pip	uv
语言	Python	Rust
依赖解析	串行	并行
缓存	基础	全局去重缓存
虚拟环境	需要 virtualenv	内置
Python 管理	需要 pyenv	内置
Lockfile	需要 pip-tools	内置
速度	基准 1x	10-100x

项目模式 vs 工具模式¶

白话： - 项目模式：管理一个项目的依赖（类似 npm），有 pyproject.toml + uv.lock - 工具模式：全局安装 CLI 工具（类似 npx/pipx），如 uv tool install ruff

Resolution（依赖解析）¶

白话： 给定你要的包列表，算出所有包的兼容版本组合。pip 经常卡在这步或报冲突，uv 用 PubGrub 算法高效解决。

安装与配置¶

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

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

# 通过 pip 安装（不推荐，但可行）
pip install uv

# 通过 Homebrew
brew install uv

# 验证
uv --version

Shell 补全¶

# Bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

快速上手¶

5 分钟入门¶

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

# 2. 添加依赖
uv add requests pandas numpy

# 3. 运行脚本（自动创建 venv + 安装依赖）
uv run python main.py

# 4. 添加开发依赖
uv add --dev pytest ruff mypy

项目结构¶

my-project/
├── pyproject.toml    # 项目元数据 + 依赖声明
├── uv.lock           # 精确锁定版本（提交到 git）
├── .python-version   # Python 版本
└── src/
    └── my_project/
        └── __init__.py

最小 pyproject.toml¶

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31",
    "pandas>=2.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=8.0",
    "ruff>=0.4",
]

进阶用法¶

1. Python 版本管理¶

# 安装 Python（替代 pyenv）
uv python install 3.12
uv python install 3.11 3.10

# 列出已安装版本
uv python list

# 固定项目 Python 版本
uv python pin 3.12

2. 虚拟环境管理¶

# 创建 venv（通常不需要手动，uv run 自动处理）
uv venv

# 指定 Python 版本
uv venv --python 3.12

# 激活（传统方式，可选）
source .venv/bin/activate

3. 依赖管理进阶¶

# 更新所有依赖
uv lock --upgrade

# 更新特定包
uv lock --upgrade-package requests

# 从 requirements.txt 迁移
uv add $(cat requirements.txt)

# 导出为 requirements.txt（兼容旧工作流）
uv export --format requirements-txt > requirements.txt

# 移除依赖
uv remove pandas

4. 工具管理（替代 pipx）¶

# 全局安装 CLI 工具
uv tool install ruff
uv tool install httpie
uv tool install jupyter

# 临时运行（不安装，类似 npx）
uvx ruff check .
uvx black --check .

# 列出已安装工具
uv tool list

5. 工作区（Monorepo）¶

# 根 pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

my-monorepo/
├── pyproject.toml
├── uv.lock          # 共享 lockfile
└── packages/
    ├── core/
    │   └── pyproject.toml
    └── api/
        └── pyproject.toml

6. Docker 优化¶

FROM python:3.12-slim

# 安装 uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# 利用缓存层
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project

# 复制代码
COPY . .
RUN uv sync --frozen

7. CI/CD (GitHub Actions)¶

- uses: astral-sh/setup-uv@v3
  with:
    version: "latest"

- run: uv sync
- run: uv run pytest
- run: uv run ruff check .

常见问题与排错¶

问题	原因	解决方案
`No solution found`	依赖版本冲突	放宽版本约束或检查冲突包
找不到 Python	未安装对应版本	`uv python install 3.x`
lockfile 冲突	多人修改	`uv lock` 重新生成
旧项目迁移	没有 pyproject.toml	`uv init` 后 `uv add` 已有依赖
缓存占空间	全局缓存积累	`uv cache clean`

面试高频考点¶

uv 为什么比 pip 快？
Rust 实现、并行解析、全局缓存去重、高效网络层
lockfile 的作用？
固定所有依赖的精确版本 + hash，保证跨环境一致
uv 与 Poetry/PDM 的区别？
速度（量级差距）、Rust 无 Python 依赖、统一了更多功能
如何保证团队开发环境一致？
提交 uv.lock + .python-version，CI 用 uv sync --frozen
虚拟环境的必要性？
项目依赖隔离、避免系统 Python 污染、可重现构建