一、 核心理念与优势

UV​ 是由 Astral 团队（Ruff 作者）开发的 极速、一体化​ Python 工具链。它用 Rust 编写，速度比 pip 快 10-100 倍，将包管理、虚拟环境、项目脚手架、打包发布等功能整合在一个工具中，终结了 pip + virtualenv/venv + setuptools + pip-tools的碎片化工作流。

二、 核心工作流示例

场景1：全新项目开发

# 1. 一键创建项目（自动生成pyproject.toml、README、gitignore等）
uv init myapp --python 3.11 --license MIT
cd myapp

# 2. 添加依赖
uv add fastapi pydantic
uv add --dev pytest httpx black

# 3. 安装所有依赖（自动创建虚拟环境）
uv install --dev

# 4. 生成锁文件确保一致性（建议提交到版本控制）
uv lock

# 5. 不激活环境直接运行代码/工具
uv run python main.py
uv run pytest
uv run black .

场景2：团队协作/CI/CD

# 克隆项目后，严格按锁文件安装（保证环境完全一致）
git clone <repo>
cd <project>
uv install --locked  # 关键！防止"在我机器上是好的"问题

# 导出传统requirements.txt（兼容Docker等工具）
uv export --locked --output requirements.txt
uv export --dev --locked --output requirements-dev.txt

三、 完整命令参考表

功能分类	核心命令	常用参数	示例
初始化​	uv init	--python, --license, --no-virtual-env	uv init api --python 3.12
包管理​	uv add	--dev, --git, -e	uv add --dev "pytest>=7.0"
	uv install	--dev, --locked, --frozen, --sync	uv install --locked --sync
	uv remove		uv remove requests+ uv lock
	uv update	--all, --preview	uv update --all --preview
	uv show	--outdated	uv show --outdated
虚拟环境​	uv venv create	--python, --name, --path	uv venv create --name prod --python 3.11
	uv venv list	--details	uv venv list --details
	uv run		uv run python script.py
依赖管理​	uv lock		uv lock(生成/更新锁文件)
	uv export	--dev, --locked, --output	uv export --locked > req.txt
构建发布​	uv build	--sdist, --wheel	uv build --wheel
	uv publish	--token	uv publish --token $PYPI_TOKEN
配置维护​	uv config	set, get, --global	uv config set index.url <镜像>
	uv check	--dev, --security	uv check --security
	uv self update		uv self update

四、 关键最佳实践

1. 锁定环境（最重要！）

# 开发中更改依赖后必须运行
uv add new-package
uv lock  # 更新uv.lock
git add uv.lock  # 提交到版本控制

# 部署/CI中严格按锁文件安装
uv install --locked

2. 智能清理环境

# 清理未声明包，保持环境纯净
uv install --sync

# 等价操作
uv sync

3. 混合环境管理

# 创建不同Python版本的环境
uv venv create --name py310 --python 3.10
uv venv create --name py311 --python 3.11

# 在不同环境中工作
uv venv activate py310
# 或使用 uv run 避免激活
uv run --with-venv py310 python script.py

4. 从传统工具迁移

# 从 requirements.txt 迁移
cat requirements.txt | xargs uv add
uv lock

# 从已存在项目开始使用
cd existing-project
uv venv create
uv install

五、 高级技巧

1. Git依赖与本地包

# Git依赖（支持分支、标签、提交）
uv add --git https://github.com/user/repo.git
uv add --git https://github.com/user/repo.git@v1.0.0
uv add --git https://github.com/user/repo.git@main#subdirectory=pkg

# 可编辑模式（开发本地包）
uv add -e ../my-local-package

2. 镜像源配置（国内加速）

# 设置全局镜像
uv config set --global index.url https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用环境变量
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

3. 一次性脚本

# 无需先安装，自动处理依赖
uv run --with numpy pandas "python analyze.py"

# 指定Python版本
uv run --python 3.10 --with matplotlib "python plot.py"

六、 性能与兼容性

特性	UV 表现	传统方案对比
冷启动安装​	缓存+并行下载，极快	pip 的 10-100x
热启动安装​	毫秒级（复用缓存）	pip 仍需解析
依赖解析​	PubGrub算法，快速准确	pip 较慢，poetry 中等
虚拟环境创建​	复用工具链，<1秒	python -m venv 2-5秒
兼容性​	完全兼容 pip/requirements.txt	可无缝迁移现有项目

七、 总结清单

1. 新项目启动：uv init → uv add → uv lock → uv install

2. 日常开发：修改依赖后必运行 uv lock并提交锁文件

3. 团队协作：始终使用 uv install --locked保证一致性

4. CI/CD：使用 uv sync或 uv install --locked --sync

5. 环境管理：多用 uv run避免手动激活，命名环境便于切换

6. 构建发布：uv build → uv publish一体化完成

7. 传统迁移：直接从 requirements.txt开始，逐步替换 pip 命令

八、 快速速查表

# 开发流程
uv init <项目名> --python 3.11
uv add <包>; uv add --dev <工具>
uv lock
uv install --dev
uv run <命令>

# 团队/部署
git pull
uv install --locked
uv run <启动命令>

# 包管理
uv add <包>[@版本]  # 添加
uv remove <包>      # 移除
uv update --all     # 更新
uv show --outdated  # 检查更新

# 环境
uv venv create --name <环境名>
uv venv list
uv run --with-venv <环境名> <命令>

# 导出
uv export --locked > requirements.txt
uv export --dev --locked > requirements-dev.txt

UV 是 更快、更统一、更简单​ 的 Python 工具链。只需记住核心模式：uv add → uv lock → uv install --locked，即可解决 90% 的 Python 包管理和环境问题。