[!info] related notes

• 所属 MOC: Python MOC, 开发环境 MOC
• 操作指南: 安装 uv 并管理 Python 项目
• 关系笔记: Python 包管理演进
• 相邻工具: virtualenv, poetry, ruff, pylance

uv

这是什么

uv 是 Astral 提供的 Python 工具链。

它把过去经常分散在多个工具里的职责整合到统一 CLI：

Python 版本
+
虚拟环境
+
项目与依赖
+
lockfile
+
命令执行
+
独立 CLI 工具运行

因此理解 uv 时，不要只把它等同为“更快的 pip”。

核心角色

Python 版本管理

uv 可以安装、发现和为项目固定 Python 版本。

这部分和 pyenv 的问题域有重叠。

Project / Dependency Management

围绕：

• pyproject.toml；
• dependency declarations；
• uv.lock；
• sync；

建立可重复项目环境。

这部分和 Poetry / PDM 等项目管理工具的问题域有重叠。

Virtual Environment

uv 可以创建和管理项目环境，不要求开发者先手工激活一个 venv 才能运行命令。

Tool Runner

uvx / tool workflow 适合运行独立 Python CLI，而不需要把所有工具永久安装进全局 Python。

这部分对应 pipx 一类工具的场景。

pip Compatibility

uv 同时提供 pip 风格接口，方便既有 requirements / venv 工作流迁移或加速。

但 pip compatibility 与 uv project workflow 是不同使用模式，不应无意识维护两套彼此漂移的项目依赖契约。

一个项目里的心智模型

pyproject.toml
= 项目声明

uv.lock
= 解析后的可重复依赖结果

.python-version / requires-python
= Python 版本约束的一部分

.venv
= 可重建的本地环境

uv sync
= 从声明恢复环境

uv run
= 在项目环境中执行命令

重点是：

本地环境是 projection，不是项目依赖的 Source of Truth。

与 pip / virtualenv / pyenv / Poetry 的关系

uv 覆盖了这些工具的部分或大部分常见职责，但“能覆盖”不等于所有项目都应该立即迁移。

选择时应看：

• 已有项目契约；
• lockfile 与 CI；
• 私有源 / 构建后端；
• 团队熟悉度；
• 特殊插件或发布流程。

完整演进关系看 Python 包管理演进。

适合的场景

• 希望统一 Python 项目工具链；
• 新项目需要 lockfile + 可重复环境；
• CI 中希望减少环境建立复杂度；
• 需要同时管理 Python 版本、项目依赖和 CLI 工具；
• 希望减少“全局 Python / 当前 venv 到底是谁”的隐式状态。

边界

• uv 不是 Python 解释器本身；
• uv 不是类型检查器；
• uv 不是 IDE language server；
• uv 不能替代项目自己的测试、lint、build backend 设计；
• 迁移已有 Poetry/pip-tools/requirements 工作流前仍要确认团队契约。

怎么开始

具体安装、初始化、add/sync/run 与验证流程统一放在：

安装 uv 并管理 Python 项目

本页不维护第二份命令速查。

官方入口

• Docs: https://docs.astral.sh/uv/
• GitHub: https://github.com/astral-sh/uv