[!info] related notes

• 工具对象: uv
• 所属 MOC: Python MOC, 开发环境 MOC
• 关系笔记: Python 包管理演进
• 相邻工具: virtualenv, poetry

安装 uv 并管理 Python 项目

目标

完成后应能观察到：

uv --version
→ uv 可执行

uv run python --version
→ 项目使用预期 Python

uv sync
→ 根据 pyproject.toml / uv.lock 得到可重复环境

uv run <command>
→ 命令在项目环境内执行

前置条件

• Windows、macOS 或 Linux；
• 能访问 uv 官方发布源或系统包管理器；
• 新项目建议使用 pyproject.toml 作为项目元数据入口。

具体安装命令可能随平台变化；长期以 uv 官方文档为准。

1. 安装并验证

安装后先做最小验证：

uv --version

如果命令不存在，优先检查：

1. 安装是否完成；
2. uv 安装目录是否进入 PATH；
3. 当前终端是否需要重新打开。

2. 管理 Python 版本

示例：

uv python install 3.12
uv python list
uv python pin 3.12

这里要区分：

• install：让某个 Python 版本可用；
• pin：为当前项目声明偏好的 Python；
• 项目的 requires-python：声明项目真正支持的版本范围。

不要只靠本机“碰巧装了哪个 Python”作为项目契约。

3. 初始化项目

uv init my-project
cd my-project

初始化后重点检查：

• pyproject.toml；
• .python-version（如果使用 pin）；
• 后续生成的 uv.lock。

4. 添加与移除依赖

uv add requests
uv add --dev pytest
uv remove requests

原则：

依赖声明写入项目元数据，环境状态由 sync 从声明恢复。

不要把“当前虚拟环境里碰巧装了什么”当作 Source of Truth。

5. 同步环境

uv sync

验证：

uv run python -c "import sys; print(sys.executable)"

它应指向 uv 为当前项目准备/使用的项目环境，而不是随意落到系统 Python。

6. 运行项目命令

uv run python main.py
uv run pytest

uv run 的价值是让命令在项目声明对应的环境里执行，减少“终端当前激活的是哪个 venv”的隐式状态。

7. 临时运行工具

uvx ruff check .

适合不希望把某个 CLI 永久安装进全局环境的场景。

项目本身真正依赖的工具仍应按团队契约决定是否进入 dev dependencies。

8. pip 兼容场景

uv 也提供 pip 风格接口，例如：

uv venv
uv pip install -r requirements.txt

它适合迁移或兼容已有 requirements 工作流。

但新项目如果已经使用 uv project workflow，应避免同时维护两套彼此漂移的依赖 Source of Truth。

验证清单

• uv --version 成功；
• uv run python --version 符合项目预期；
• uv sync 可从项目文件恢复环境；
• 删除本地环境后重新 sync 仍可运行；
• CI 与本地读取同一份项目依赖契约。

常见失败

找不到 uv

检查 PATH，并重新打开终端。

Python 版本不符合预期

同时检查：

• .python-version；
• requires-python；
• uv python list；
• 实际 uv run python --version。

本地能跑、CI 不能跑

优先确认：

• lockfile 是否提交；
• CI 是否执行 sync；
• Python 版本约束是否一致；
• 是否依赖了未声明的全局工具。

无提示执行检查

不看正文，在一个空目录完成：

1. 安装/验证 uv；
2. 固定一个 Python 版本；
3. 初始化项目；
4. 添加一个 runtime dependency 和一个 dev dependency；
5. sync 后运行一个脚本与测试；
6. 删除项目环境并重新恢复；
7. 解释 pyproject.toml、uv.lock、.python-version 与本地环境分别承担什么职责。