一、认识 uv：重塑 Python 包管理体验

uv 是由 Astral 公司（Ruff 代码检查工具的开发商）用 Rust 语言编写的现代化 Python 包管理器和项目管理工具。它的出现彻底改变了 Python 生态中"安装慢、工具散、环境乱"的痛点，一个工具就能替代 pip、venv、pip-tools、Poetry、PDM、pipx 等多款工具的核心功能。

1.1 uv 的核心优势

• 极致速度：基于 Rust 编写，依赖解析和安装速度比传统 pip 快 10-100 倍
• 功能一体化：包管理、虚拟环境、Python 版本管理、项目脚手架一站式解决
• 全局缓存：跨项目共享依赖缓存，避免重复下载，节省磁盘空间
• 标准兼容：完全遵循 PEP 标准，原生支持 pyproject.toml，无缝迁移现有项目
• 锁文件机制：内置 uv.lock 精确锁定依赖版本，保证环境可复现

1.2 安装 uv

uv 的安装非常简单，各平台通用一行命令即可：

macOS / Linux：

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

Windows（PowerShell）：

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

通过包管理器安装：

pip install uv

安装完成后，验证版本：

uv --version
# 输出示例：uv 0.4.17 (a1b2c3d 2026-02-08)

1.3 快速体验

# 创建一个新项目，使用Python 3.12 虚拟环境（如果本地没有 3.12，uv 会自动下载）
uv init my_project --python 3.12

# 可近似认为 相当于 以下命令的 简写
# uv init my_project
# uv venv --python 3.12
# uv python pin 3.12

# 安装依赖
uv add requests
# 不要用下面的 方式 安装依赖
# uv pip install requests  该方式 不会 同步版本文件 的记录

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

---

二、项目管理核心命令

2.1 uv init：初始化项目

uv init 用于快速创建一个标准的 Python 项目结构，自动生成 pyproject.toml、示例代码、Git 仓库等基础设施。

基本语法：

uv init [OPTIONS] [PATH]

常用参数：

参数	说明
--name <NAME>	指定项目名称，默认使用目录名
--python <VERSION>	指定项目 Python 版本，如 3.12
--lib	创建库项目（生成 src 目录结构）
--app	创建应用项目（默认，生成 main.py）
--no-readme	不生成 README.md
--no-git	不初始化 Git 仓库
--no-vcs	完全跳过版本控制系统初始化

实战示例：

# 1. 在当前目录创建项目
uv init

# 2. 创建一个名为 fastapi-demo 的应用项目，指定 Python 3.12
uv init fastapi-demo --python 3.12

# 3. 创建一个库项目（适合发布到 PyPI）
uv init my-library --lib

# 4. 极简初始化，不生成 Git 和 README
uv init simple-project --no-git --no-readme

执行 uv init fastapi-demo 后，项目结构如下：

fastapi-demo/
├── .git/               # Git 仓库
├── .gitignore          # Python 标准忽略规则
├── .python-version     # Python 版本声明文件
├── README.md           # 项目说明文档
├── hello.py            # 示例入口文件
└── pyproject.toml      # 项目配置与依赖声明

生成的 pyproject.toml 内容示例：

[project]
name = "fastapi-demo"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.12"
dependencies = []

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

💡 小提示：首次执行 uv sync 或 uv run 后，会自动创建 .venv 虚拟环境目录和 uv.lock 锁文件。

2.2 uv add：添加依赖

uv add 是最常用的命令之一，用于向项目添加依赖包。它会自动更新 pyproject.toml、重新解析依赖、更新锁文件，并同步安装到虚拟环境。

基本语法：

uv add [OPTIONS] <PACKAGES>...

常用参数：

参数	说明
--dev	添加为开发依赖（对应 [tool.uv.dev-dependencies]）
--group <GROUP>	添加到指定依赖组，如 docs、test
--version <VERSION>	指定版本约束，如 ==2.31.0
--editable / -e	以可编辑模式安装（本地开发包）
--no-sync	只更新配置和锁文件，不安装到虚拟环境
--frozen	严格按照现有锁文件操作，不更新版本
-r <FILE>	从 requirements.txt 文件批量添加

实战示例：

# 1. 添加单个生产依赖
uv add requests

# 2. 添加多个依赖包
uv add fastapi uvicorn pydantic

# 3. 指定精确版本
uv add 'requests==2.32.3'

# 4. 指定版本范围
uv add 'httpx>=0.27.0,<0.28'

# 5. 添加开发依赖（pytest、ruff 等测试/工具类）
uv add --dev pytest ruff mypy

# 6. 添加到自定义依赖组
uv add --group docs mkdocs mkdocs-material

# 7. 从 Git 仓库安装
uv add git+https://github.com/psf/requests.git

# 8. 从 Git 指定分支/标签安装
uv add git+https://github.com/psf/requests.git@v2.32.3

# 9. 从本地目录以可编辑模式安装
uv add -e ../my-local-package

# 10. 从 requirements.txt 批量导入
uv add -r requirements.txt

执行 uv add fastapi uvicorn 后，pyproject.toml 会自动更新：

[project]
name = "fastapi-demo"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn>=0.30.0",
]

2.3 uv remove：移除依赖

uv remove 用于从项目中移除依赖包，同步更新配置文件、锁文件和虚拟环境。

基本语法：

uv remove [OPTIONS] <PACKAGES>...

常用参数：

参数	说明
--dev	从开发依赖中移除
--group <GROUP>	从指定依赖组移除
--no-sync	只更新配置，不卸载虚拟环境中的包
--frozen	不重新解析锁文件

实战示例：

# 1. 移除单个依赖
uv remove requests

# 2. 移除多个依赖
uv remove fastapi uvicorn

# 3. 移除开发依赖
uv remove --dev pytest

# 4. 从自定义组移除
uv remove --group docs mkdocs

⚠️ 注意：如果依赖包是通过 uv pip install 手动安装的，uv remove 不会将其卸载，它只管理 pyproject.toml 中声明的依赖。

2.4 uv sync：同步项目环境

uv sync 是项目环境同步的核心命令，它会根据 pyproject.toml 和 uv.lock 安装所有依赖，确保本地环境与锁文件完全一致。

基本语法：

uv sync [OPTIONS]

常用参数：

参数	说明
--frozen	严格按照锁文件安装，锁文件过时则报错（CI/CD 必备）
--no-dev	不安装开发依赖（生产环境部署用）
--group <GROUP>	额外安装指定依赖组
--all-groups	安装所有依赖组
--reinstall	强制重新安装所有包
--reinstall-package <PKG>	强制重新安装指定包

实战示例：

# 1. 完整同步（安装生产+开发依赖）
uv sync

# 2. 生产环境部署，只装生产依赖
uv sync --no-dev

# 3. CI/CD 环境，严格锁定版本
uv sync --frozen

# 4. 同步时额外安装 docs 组
uv sync --group docs

# 5. 强制重装某个包（解决包损坏问题）
uv sync --reinstall-package requests

# 6. 全新重装所有依赖
uv sync --reinstall

💡 CI/CD 最佳实践：在流水线中务必使用 uv sync --frozen，它会确保完全按照 uv.lock 安装，任何依赖变动都会导致构建失败，从而保证环境一致性。

2.5 uv lock：生成/更新锁文件

uv lock 用于解析所有依赖并生成 uv.lock 锁文件，锁定每个包的精确版本和哈希值，确保跨环境的可复现性。

基本语法：

uv lock [OPTIONS]

常用参数：

参数	说明
--upgrade	升级所有依赖到最新兼容版本
--upgrade-package <PKG>	升级指定包到最新版本
--refresh	刷新已有的锁文件（不改变版本，只更新元数据）

实战示例：

# 1. 生成或更新锁文件
uv lock

# 2. 升级所有依赖到最新兼容版本
uv lock --upgrade

# 3. 只升级 requests 包
uv lock --upgrade-package requests

# 4. 同时升级多个包
uv lock --upgrade-package requests --upgrade-package httpx

🔒 锁文件原理：uv.lock 记录了每个依赖的精确版本、下载 URL、哈希校验值，以及完整的依赖树关系。建议将 uv.lock 提交到 Git 仓库，团队成员和部署环境都能得到完全一致的依赖。

---

三、运行与环境命令

3.1 uv run：在虚拟环境中执行命令

uv run 可以在项目的虚拟环境中执行任意命令或脚本，无需手动激活虚拟环境，是日常开发最高频的命令之一。

基本语法：

uv run [OPTIONS] <COMMAND> [ARGS]...

常用参数：

参数	说明
--with <PKG>	临时注入额外的包再运行
--no-sync	运行前不自动同步环境
--python <VERSION>	指定 Python 版本运行

实战示例：

# 1. 运行 Python 脚本
uv run python main.py

# 2. 运行项目内的命令行工具
uv run pytest tests/ -v
uv run ruff check src/
uv run uvicorn main:app --reload --port 8000

# 3. 临时带上额外包运行
uv run --with ipython ipython

# 4. 直接执行模块
uv run python -m http.server 8000

# 5. 指定 Python 版本运行
uv run --python 3.11 python --version

💡 实用技巧：uv run 会自动检测项目根目录，即使你在子目录中执行，也能正确找到虚拟环境。这比手动 source activate 方便太多。

3.2 uv run 脚本执行

如果 pyproject.toml 里定义了脚本入口

[project.scripts]
wtt = "your_package.main:main"

然后就可以 ：

uv run wtt

3.3 uv venv：虚拟环境管理

虽然 uv 项目模式下会自动管理虚拟环境，但 uv venv 提供了手动创建和管理虚拟环境的能力，兼容传统工作流。

基本语法：

uv venv [OPTIONS] [PATH]

常用参数：

参数	说明
--python <VERSION>	指定 Python 版本
--prompt <NAME>	设置虚拟环境提示符名称
--system-site-packages	允许访问系统包
--seed	预装 pip、setuptools、wheel

实战示例：

# 1. 在当前目录创建 .venv
uv venv

# 2. 指定路径和 Python 版本
uv venv .venv311 --python 3.11

# 3. 创建时预装 pip（兼容旧工具）
uv venv --seed

# 4. 自定义提示符
uv venv --prompt myproject

创建后激活方式与标准 venv 一致：

# macOS / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

3.4 uv python：Python 版本管理

uv 内置了 Python 版本管理能力，可以自动下载和管理多个 Python 版本，无需额外安装 pyenv。

常用子命令：

# 1. 列出已安装的 Python 版本
uv python list

# 2. 列出所有可安装的 Python 版本
uv python list --all

# 3. 安装指定 Python 版本
uv python install 3.12
uv python install 3.11.8

# 4. 卸载 Python 版本
uv python uninstall 3.10

# 5. 查找符合要求的 Python
uv python find 3.11+

# 6. 显示 uv 使用的 Python 路径
uv python which

✨ 亮点：uv 会自动下载官方 Python 发行版并管理在全局缓存中，项目通过 .python-version 文件声明版本，uv 自动匹配使用，真正做到了"声明即拥有"。

---

四、pip 兼容模式：uv pip

对于习惯了 pip 命令或需要维护传统 requirements.txt 项目的用户，uv 提供了 uv pip 子命令，完全兼容 pip 的接口，但速度提升数十倍。

4.1 常用 pip 兼容命令

# 1. 安装包
uv pip install requests
uv pip install requests==2.32.3
uv pip install -r requirements.txt

# 2. 升级包
uv pip install --upgrade requests

# 3. 卸载包
uv pip uninstall requests

# 4. 列出已安装的包
uv pip list
uv pip list --outdated  # 查看可升级的包

# 5. 冻结依赖
uv pip freeze > requirements.txt

# 6. 显示包信息
uv pip show requests

# 7. 检查依赖完整性
uv pip check

4.2 pip 模式高级参数

# 指定索引源（国内镜像加速）
uv pip install torch --index-url https://download.pytorch.org/whl/cu121

# 使用额外索引源
uv pip install package --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 从 requirements.txt 安装并严格锁定
uv pip install -r requirements.txt --strict

💡 迁移建议：如果你的项目还在用 requirements.txt，可以先用 uv pip 享受速度提升，再逐步迁移到 pyproject.toml + uv.lock 的现代化项目管理模式。

---

五、实用辅助命令

5.1 uv tree：查看依赖树

uv tree 以树形结构展示项目的完整依赖关系，帮助你理解依赖传递和排查版本冲突。

# 1. 显示完整依赖树
uv tree

# 2. 只显示生产依赖
uv tree --no-dev

# 3. 反向查找某个包被谁依赖
uv tree --invert requests

# 4. 显示重复的包（排查版本冲突）
uv tree --duplicates

输出示例：

fastapi-demo v0.1.0
├── fastapi v0.115.0
│   ├── pydantic v2.9.2
│   │   ├── annotated-types v0.7.0
│   │   ├── pydantic-core v2.23.4
│   │   └── typing-extensions v4.12.2
│   ├── starlette v0.38.6
│   │   └── anyio v4.6.0
│   │       ├── idna v3.10
│   │       └── sniffio v1.3.1
│   └── typing-extensions v4.12.2
└── uvicorn v0.30.6
    ├── click v8.1.7
    └── h11 v0.14.0

5.2 uv export：导出依赖

uv export 可以将 uv.lock 导出为其他格式，方便与传统工具或部署平台兼容。

# 1. 导出为 requirements.txt 格式
uv export > requirements.txt

# 2. 只导出生产依赖
uv export --no-dev > requirements.txt

# 3. 导出包含哈希校验（增强安全性）
uv export --hashes > requirements.txt

# 4. 导出为 constraints 文件
uv export --format constraints > constraints.txt

5.3 uv cache：缓存管理

uv 的全局缓存是其高性能的核心机制，uv cache 命令可以查看和管理缓存。

# 1. 查看缓存目录位置
uv cache dir

# 2. 查看缓存统计信息
uv cache info

# 3. 清理无用缓存（自动清理过期和未使用的包）
uv cache prune

# 4. 完全清空缓存
uv cache clean

# 5. 验证缓存完整性
uv cache verify

💡 缓存位置：

• macOS/Linux: ~/.cache/uv
• Windows: %LOCALAPPDATA%\uv\cache

CI/CD 环境中可以缓存这个目录大幅提升构建速度。

5.4 uv tool：全局工具管理

uv tool 类似 pipx，用于安装和管理全局 Python 命令行工具，每个工具拥有独立的虚拟环境，互不干扰。

# 1. 安装全局工具
uv tool install ruff
uv tool install ipython
uv tool install poetry

# 2. 列出已安装的工具
uv tool list

# 3. 升级工具
uv tool upgrade ruff

# 4. 卸载工具
uv tool uninstall ruff

# 5. 运行已安装的工具
uv tool run ruff --version

5.5 uv audit：安全审计

uv audit 用于扫描项目依赖中的已知安全漏洞，帮助你及时发现和修复风险。

# 1. 审计所有依赖
uv audit

# 2. 只审计生产依赖
uv audit --no-dev

# 3. 输出 JSON 格式（便于集成 CI）
uv audit --format json

---

六、构建与发布

6.1 uv build：构建包

uv build 可以将项目构建为源码分发包（sdist）和 wheel 包，无需额外安装 build 工具。

# 1. 构建 sdist 和 wheel
uv build

# 2. 只构建 wheel
uv build --wheel

# 3. 只构建源码包
uv build --sdist

# 4. 指定输出目录
uv build --out dist/

6.2 uv publish：发布到 PyPI

# 1. 发布到 PyPI（需要用户名和密码）
uv publish

# 2. 使用 API Token 发布
uv publish --token pypi-xxxxxxxxxx

# 3. 发布到测试环境
uv publish --index-url https://test.pypi.org/legacy/

---

七、高级配置与最佳实践

7.1 配置国内镜像源

默认从 PyPI 下载在国内速度较慢，可以配置清华镜像源加速。在项目根目录创建 uv.toml 或在 pyproject.toml 中配置：

# pyproject.toml
[[tool.uv.index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

或者通过环境变量全局配置：

export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

7.2 多索引源与专用包

对于 PyTorch、TensorFlow 等有专用索引的包，可以单独配置：

[[tool.uv.index]]
name = "pytorch-cu121"
url = "https://download.pytorch.org/whl/cu121"
explicit = true  # 只用于明确指定的包

[tool.uv.sources]
torch = { index = "pytorch-cu121" }
torchvision = { index = "pytorch-cu121" }

7.3 CI/CD 最佳实践

GitHub Actions 中使用 uv 的典型配置：

- name: Install uv
  uses: astral-sh/setup-uv@v3

- name: Sync dependencies
  run: uv sync --frozen

- name: Run tests
  run: uv run pytest

关键要点：

• 使用 --frozen 确保严格按照锁文件安装
• 缓存 ~/.cache/uv 目录加速后续构建
• 所有命令通过 uv run 执行，确保环境一致

7.4 从 Poetry / PDM 迁移

迁移到 uv 非常简单：

1. 保留 pyproject.toml 中的依赖声明
2. 删除旧的锁文件（poetry.lock / pdm.lock）
3. 运行 uv lock 生成 uv.lock
4. 运行 uv sync 安装依赖
5. 更新 .gitignore，添加 .venv

7.5 常用环境变量

变量名	作用
UV_CACHE_DIR	自定义缓存目录
UV_INDEX_URL	默认 PyPI 索引地址
UV_NO_CACHE	禁用缓存（设为 1）
UV_PYTHON	指定默认 Python 解释器
UV_FROZEN	强制 frozen 模式

---

八、性能为什么这么快？原理简析

uv 之所以比传统 pip 快几十上百倍，核心在于以下几点技术优化：

1. Rust 语言实现：零成本抽象、内存安全、原生并发，比 Python 解释器执行快得多
2. 全局共享缓存：所有项目共享同一份下载缓存和 wheel 缓存，避免重复下载和编译
3. 并行下载与安装：充分利用多核 CPU，同时下载和安装多个包
4. 增量依赖解析：基于现代 SAT 求解算法，依赖解析速度数量级提升
5. 二进制 wheel 优先：优先使用预编译 wheel，避免本地编译耗时

---

九、常见问题与技巧

Q: uv 和 pip 可以混用吗？
A: 可以但不推荐。uv 完全兼容 venv 标准，pip 安装的包 uv 能识别。但混用会导致锁文件和实际环境不一致，建议统一使用 uv 管理。

Q: uv.lock 需要提交到 Git 吗？
A: 应用项目强烈建议提交，保证团队和部署环境一致；库项目（Library）可选，通常不提交，让使用者自己解析。

Q: 可以离线使用吗？
A: 可以。只要缓存中有对应包，加上 --offline 参数即可完全离线安装。

Q: uv 支持 conda 吗？
A: uv 不管理 conda 包，但可以和 conda 环境共存。如果只是 Python 包管理，uv 完全可以替代 conda。

Q: 如何查看某个命令的详细帮助？
A: 使用 uv help <命令>，例如 uv help add，会列出所有参数和说明。

---

十、命令速查表

场景	命令
新建项目	uv init my-project
添加依赖	uv add requests
添加开发依赖	uv add --dev pytest
同步环境	uv sync
CI 严格同步	uv sync --frozen
运行脚本	uv run python main.py
运行测试	uv run pytest
升级所有依赖	uv lock --upgrade
查看依赖树	uv tree
安装全局工具	uv tool install ruff
安装 Python	uv python install 3.12
清理缓存	uv cache prune

---

结语

uv 代表了 Python 包管理的下一代方向：极致的性能、统一的体验、标准的兼容。从简单的脚本项目到复杂的生产级应用，uv 都能提供流畅高效的开发体验。掌握本文介绍的这些核心命令和参数，足以覆盖 95% 以上的日常开发场景。

建议从现有项目开始尝试，先用 uv pip 感受速度提升，再逐步迁移到完整的项目管理模式。一旦习惯了 uv 的速度和便利，就很难再回到传统的 pip 工作流了。