uv 极速 Python 包管理指南
uv 是由 Astral 团队（也是 Ruff 的作者）用 Rust 编写的下一代 Python 包管理工具。它以惊人的速度（通常比 pip 快 10-100 倍）和单一二进制的部署方式，一站式替代了 pip、pip-tools、pipenv、poetry、virtualenv、pyenv 等一整套传统工具链。
本文记录了 uv 在生产与日常开发中的安装、项目化管理、多版本 Python 管理以及国内镜像加速的高频用法。
1. 安装 uv
uv 是单一二进制文件，无任何运行时依赖，安装极其简单。
在线一键安装 (Linux / macOS)
# 官方推荐安装方式（通过 curl）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者使用 wget 方式安装
wget -qO- https://astral.sh/uv/install.sh | sh
如果 astral.sh 在国内访问较慢，可以通过 pip 从国内镜像源安装 uv：
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
验证安装
# 查看 uv 版本
uv --version
输出类似 uv 0.4.x 即代表安装成功！
2. Python 版本管理（替代 pyenv）
uv 内置了 Python 多版本管理能力，无需再单独安装 pyenv，且下载速度极快（基于 Rust 并发下载与解压）。
# 1. 列出所有可供安装的 Python 版本（远程版本）
uv python list --all-versions
# 2. 安装指定的 Python 版本（例如 3.12）
uv python install 3.12
# 3. 安装多个版本
uv python install 3.11 3.12 3.13
# 4. 查看本地已安装的所有 Python 版本
uv python list
# 5. 卸载不需要的 Python 版本
uv python uninstall 3.11
3. 项目化管理（替代 poetry / pipenv）
uv 的核心杀手锏之一是项目级管理。它会自动维护 pyproject.toml、uv.lock 锁文件以及 .venv 虚拟环境，工作流比 poetry 更简洁、更快。
初始化新项目
# 在当前目录初始化一个 Python 项目（自动生成 pyproject.toml）
uv init my-project
cd my-project
依赖安装与增删
# 1. 根据 pyproject.toml 同步安装所有依赖（自动创建 .venv）
uv sync
# 2. 添加运行时依赖（自动写入 pyproject.toml 并更新 lock 文件）
uv add fastapi
uv add "pydantic>=2.0"
# 3. 添加开发依赖（写入 dev 依赖组）
uv add --dev pytest
uv add --dev ruff
# 4. 移除依赖
uv remove fastapi
运行项目命令
uv 提供了 uv run，可以在不手动激活虚拟环境的情况下直接执行命令，非常适合 CI/CD 场景：
# 直接在项目虚拟环境中运行脚本
uv run main.py
# 直接运行 pytest 测试
uv run pytest -v
# 直接启动 uvicorn 服务
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
4. 兼容 pip 的工作流（零迁移成本）
如果您暂时不想改造现有项目结构，uv 可以无缝替代 pip，所有 pip 命令只需把 pip 换成 uv pip 即可，速度立竿见影。
# 1. 创建并激活虚拟环境（兼容 virtualenv）
uv venv
source .venv/bin/activate
# 2. 安装依赖（等价于 pip install，但快 10-100 倍）
uv pip install -r requirements.txt
uv pip install fastapi
# 3. 冻结当前依赖到 requirements.txt
uv pip freeze > requirements.txt
# 4. 卸载依赖
uv pip uninstall fastapi
5. 生产调优与常见问题解决
1. 配置国内镜像源加速（pypi 镜像）
uv 默认从 PyPI 官方源下载，国内可能较慢。可以通过环境变量或配置文件指定镜像源：
# 临时方式：通过环境变量指定镜像源
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 然后正常执行 uv 命令
uv pip install -r requirements.txt
也可以在项目根目录的 pyproject.toml 中持久化配置：
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
2. 离线环境 / 内网部署构建缓存
uv 拥有强大的全局缓存机制，默认缓存路径为 ~/.cache/uv。在内网或 CI 环境中，合理利用缓存可以大幅加速构建：
# 设置缓存目录（常用于 CI Runner 持久化缓存）
export UV_CACHE_DIR=/ci-cache/uv
# 离线模式：只使用本地缓存，不访问网络
uv sync --offline
# 清理缓存
uv cache clean
3. 锁文件 (uv.lock) 的作用与冲突解决
uv.lock 类似于 poetry.lock 或 package-lock.json，记录了所有依赖的精确版本与哈希值，用于保证团队与生产环境依赖完全一致。
# 当 pyproject.toml 修改后，重新生成 lock 文件
uv lock
# 严格按照 lock 文件同步依赖（CI/生产环境推荐）
uv sync --frozen
生产部署或 CI 构建时，强烈建议使用 uv sync --frozen，它会严格依据 uv.lock 安装，不允许任何依赖版本漂移，从而避免"在我本地能跑"的经典问题。