uv Python 项目管理最佳实践指南
uv 是 Astral 团队开发的极速 Python 包与项目管理工具，旨在统一和简化开发流程。它既提供了现代项目模式（声明式依赖、锁定文件、自动虚拟环境），又能作为 pip、pip-tools、poetry 等工具的替代品。本文将从零开始，带你掌握 uv 的安装、项目构建、核心命令区别及最佳实践。
1. 安装与准备
在系统上安装 uv：
macOS / Linux
1
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell)
1
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
安装后验证：uv --version。
若需配置国内 PyPI 镜像（如清华源），可设置环境变量：
1 | export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # Linux/macOS |
2. 从零开始构建项目与虚拟环境
uv 推崇项目即环境，无需手动激活虚拟环境。
1 | mkdir my-project && cd my-project |
生成的文件：
pyproject.toml– 项目元数据与依赖声明（唯一真相来源）uv.lock– 精确依赖快照（需提交 Git）.venv/– 项目专属虚拟环境.python-version– 锁定 Python 版本README.md、.gitignore
3. 依赖管理
3.1 使用 uv add（推荐项目模式）
1 | uv add requests # 添加依赖，自动更新 pyproject.toml 和 uv.lock |
3.2 传统方式：uv pip install
作为 pip 的替代，uv pip install 更快速，但它不会修改项目配置文件，只影响当前环境。
1 | uv pip install requests # 安装到当前激活的环境或全局 |
3.3 从 requirements.txt 迁移
| 命令 | 作用 | 是否修改 pyproject.toml |
|---|---|---|
uv pip sync requirements.txt |
使当前环境与 requirements.txt 严格一致（会删除多余包） | ❌ 否 |
uv add -r requirements.txt |
将依赖导入 pyproject.toml，并生成 uv.lock（迁移到项目模式） | ✅ 是 |
建议：新项目用 uv add；旧项目用 uv add -r 完成迁移。
4. 运行脚本与工具
4.1 uv run – 在项目环境中运行
uv run 会在项目的虚拟环境中执行命令，无需手动激活。
1 | uv run python main.py # 运行项目脚本 |
4.2 uvx / uv tool run – 临时运行独立工具
uvx 在一个临时隔离环境中运行工具，不依赖当前项目。
1 | uvx ruff check . # 运行 ruff 格式化工具（自动下载缓存） |
4.3 uv tool install – 持久化安装全局工具
与 uvx 不同，uv tool install 将工具安装到持久化目录，并链接到 PATH，之后可作为系统命令直接调用。
1 | uv tool install ruff # 安装后可直接运行 ruff |
uv run vs uvx 区别一览
| 特性 | uv run |
uvx / uv tool run |
|---|---|---|
| 目的 | 运行项目代码或项目内依赖的命令 | 一次性运行独立的命令行工具 |
| 环境来源 | 项目根目录的 .venv 虚拟环境 |
临时创建的隔离环境 |
| 依赖可见性 | 可访问项目中声明的所有依赖 | 完全隔离，无法访问项目依赖 |
| 典型用例 | python script.py, pytest |
ruff, black, httpie |
5. 指定 uvx 的环境与版本
在日常交互中，uvx 默认会优先使用已安装的持久化版本（uv tool install），否则拉取最新兼容版本。但在可重现场景（CI、脚本、团队共享）中，建议显式指定：
- 指定工具版本：
uvx ruff@0.5.0 - 指定 Python 版本：
uvx --python 3.11 black - 同时指定：
uvx --python 3.12 --from pytest@8.2.0 pytest - 强制全新隔离环境：
uvx --isolated ruff
💡 经验法则：日常交互不指定，生产/自动化必须锁版。
6. 进阶：工作区、CI/CD 与容器化
工作区（Monorepo）
在根目录 pyproject.toml 中定义：
1 | [tool.uv.workspace] |
单一锁文件保证全局一致性。
CI/CD（GitHub Actions）
1 | - uses: astral-sh/setup-uv@v3 |
容器化（Docker 多阶段构建）
1 | FROM ghcr.io/astral-sh/uv:latest AS builder |
7. 核心命令速查表
| 功能分类 | 命令 | 说明 |
|---|---|---|
| 初始化 | uv init --python 3.12 |
新建项目并锁定 Python 版本 |
| 依赖管理 | uv add <pkg> |
添加依赖并更新锁文件 |
uv add --dev <pkg> |
添加开发依赖 | |
uv remove <pkg> |
移除依赖 | |
uv sync |
同步环境与锁文件 | |
| 运行/执行 | uv run <cmd> |
在项目环境中运行命令 |
uvx <tool> |
临时运行独立工具 | |
| 工具安装 | uv tool install <tool> |
持久化安装全局工具 |
| 迁移兼容 | uv add -r requirements.txt |
导入 requirements.txt 到项目模式 |
uv pip sync requirements.txt |
使环境与 requirements.txt 严格一致 |
8. 常见区别对比
uv add vs uv pip install
uv add |
uv pip install |
|
|---|---|---|
修改 pyproject.toml |
✅ 是 | ❌ 否 |
生成/更新 uv.lock |
✅ 是 | ❌ 否 |
| 适用场景 | 项目开发（现代模式） | 一次性安装或传统工作流 |
uv pip sync vs uv add -r
uv pip sync requirements.txt |
uv add -r requirements.txt |
|
|---|---|---|
| 用途 | 使当前环境与 txt 严格一致 | 迁移依赖到项目模式 |
是否创建 pyproject.toml |
❌ | ✅（若不存在） |
| 是否会删除多余包 | ✅ 会 | ❌ 只添加 |
uv run vs uvx
uv run |
uvx |
|
|---|---|---|
| 依赖项目环境 | 是 | 否 |
| 需要项目初始化 | 是 | 否 |
| 典型例子 | uv run python app.py |
uvx ruff check . |
好的，我已将您提供的这段话作为独立的观点小节，融入到博客原文中。请查看以下更新后的内容（新增部分位于“常见区别对比”与“总结最佳实践”之间）：
9. 关于全局 Python 环境
uv 管理项目环境的方式，uv 本身不建议直接修改系统 Python 环境，这与使用一个“干净”的全局 Python 作为运行时并不冲突，反而是一种现代、高效且更安全的选择。它将全局 Python 从复杂的项目依赖中解放出来，回归其作为系统基础组件的本来角色。
换句话说：
- 全局 Python 只用于运行操作系统工具或
uv自身。 - 所有项目依赖、版本、虚拟环境均由
uv在项目隔离层管理。 - 你无需再为不同项目频繁切换或污染全局 Python。
通过上述整合，您的观点已完整融入博客，并成为独立小节，使全文逻辑更清晰。如果需要进一步调整位置或措辞，请随时告知。
10. 总结最佳实践
- 新项目一律使用项目模式：
uv init→uv add→uv run。 - 依赖管理：始终用
uv add/uv remove，不要手动编辑pyproject.toml。 - 运行代码：用
uv run代替手动激活虚拟环境。 - 临时工具：用
uvx，若频繁使用则uv tool install。 - 可重现性：在 CI/脚本中锁定工具版本（
uvx tool@ver）和 Python 版本（--python）。 - 迁移旧项目：使用
uv add -r requirements.txt平滑过渡。 - 提交锁文件：
uv.lock必须提交 Git，保证团队环境一致。
通过遵循以上指南，你可以充分利用 uv 的高效、简洁与可重现性，享受现代化的 Python 开发体验。