Python uv 简明教程

告别依赖地狱：用 uv 重塑你的 Python 开发体验

如果你长期使用 Python，一定对下面这些场景不陌生：

1. 创建一个新项目，pip install 了几个包，忽然发现版本冲突，陷入无尽的 pip install 和 pip uninstall 循环。
2. 项目依赖文件 requirements.txt 越来越大，分不清哪些是核心依赖，哪些是依赖的依赖。
3. 想尝试新工具 poetry 或 pdm，但觉得学习曲线陡峭，又回到了老路。
4. 团队协作时，别人的环境能跑，你的就是报错，最后发现是某个底层库的版本差了一个小数点。

这些问题，归根结底是 Python 的包管理和项目依赖管理长期处于一种“自由散漫”的状态。pip 很好，但它只是个安装器；venv 能隔离环境，但用起来稍显繁琐；而 poetry、pdm 等现代工具又带来了新的概念。

今天，我要介绍一个全新的工具：uv。它由 Astral 公司（打造了 Ruff 这个极速的 Python linter）开发，旨在用一个二进制文件，解决从包安装到项目管理的绝大部分问题。它的核心特点是：极致的快和极致的简单。

一、uv 是什么？

你可以把 uv 理解为 Python 工具链的“瑞士军刀”或“超级充电器”。它在一个单一的、用 Rust 编写的二进制文件中，提供了以下功能：

• 一个超快的、兼容 pip 和 pip-tools 的包安装器。
• 一个项目虚拟环境管理器和创建器。
• 一个项目依赖锁文件生成器（类似 poetry.lock）。
• 一个快速的 pyproject.toml 项目脚手架生成器。

它的目标是成为 Python 开发者的默认工具，一个命令替代一堆命令。

二、极速安装

打开你的终端（macOS/Linux），一行命令即可安装：

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

对于 Windows 用户（PowerShell）：

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

安装完成后，重新启动终端，输入 uv --version 查看是否成功。你会立刻感受到它的第一个优点：作为一个二进制文件，它启动和运行都异常迅速。

三、从零开始一个项目：感受魔法

让我们从头创建一个名为 my-awesome-app 的项目，你会看到 uv 如何简化工作流。

1. 创建项目目录并进入

mkdir my-awesome-app && cd my-awesome-app

2. 使用 uv init 快速搭建项目脚手架

这是 uv 独有的便捷功能。

uv init

它会交互式地询问你项目名称、版本等，并一键生成标准的、现代的 pyproject.toml 文件，以及一个 README.md。这比手动编写 pyproject.toml 要友好得多。

3. 添加依赖：快到难以置信

假设我们的项目需要 requests 和 flask。使用 uv add 命令，它类似于 poetry add。

uv add requests flask

感受一下速度。你会发现安装过程几乎是瞬间完成的。uv 不仅从网络下载快，其内部的依赖解析算法也极其高效。

此时，查看你的 pyproject.toml，依赖已经被自动添加：

[project]
name = "my-awesome-app"
version = "0.1.0"
dependencies = [
    "requests",
    "flask",
]

同时，它会生成一个 uv.lock 文件，精确锁定了所有依赖（包括次级依赖）的版本，确保项目在任何地方都能完全复现。

4. 进入虚拟环境并运行 Python

uv 自动管理着虚拟环境。你可以用 uv venv 显式创建一个，但更简单的方式是直接使用 uv run。

# 直接运行一个命令，uv 会确保它在正确的虚拟环境中执行
uv run python -c "import requests; print(requests.__version__)"

# 或者启动一个在虚拟环境中的 Python 解释器 shell
uv python

你不需要手动 source venv/bin/activate，uv run 和 uv python 帮你处理了一切，减少了上下文切换。

四、在已有项目中使用 uv

如果你已经有一个使用 requirements.txt 或 pyproject.toml 的项目，uv 可以无缝接入。

场景 A：只有 requirements.txt

# 安装所有依赖（速度比 pip install -r requirements.txt 快一个数量级）
uv pip install -r requirements.txt

# 或者，如果你想升级到现代工作流，可以生成 lock 文件
uv lock --requirements-in requirements.txt --locked

场景 B：已有 pyproject.toml（比如 Poetry 项目）

uv 完全支持 pyproject.toml 作为依赖源。

# 安装 pyproject.toml 中声明的所有依赖
uv sync

uv sync 是核心命令，它会读取 pyproject.toml，根据 uv.lock 安装精确版本。如果没有 uv.lock，它会解析并创建一个。

五、核心命令速查

命令	作用	传统等效命令
uv add <package>	添加依赖并更新 pyproject.toml	poetry add <package>
uv sync	同步依赖（安装/更新）	poetry install / pip install -e .
uv run <command>	在项目虚拟环境中运行命令	source venv/bin/activate && <command>
uv python	启动项目虚拟环境的 Python 解释器	source venv/bin/activate && python
uv lock	生成/更新 uv.lock 锁文件	poetry lock
uv init	交互式创建 pyproject.toml	手动创建
uv pip compile	编译 requirements.txt（高级）	pip-compile

六、为什么选择 uv？一个简单的总结

1. 速度就是王道：用 Rust 重写的依赖解析和下载逻辑，让安装包的过程从“喝杯咖啡”变成“眨下眼睛”。
2. 统一体验：一个 uv 命令涵盖了从创建、依赖管理到环境运行的全流程，无需在 pip、venv、virtualenvwrapper、poetry 之间来回切换。
3. 兼容并蓄：它尊重现有的 Python 生态。既支持传统的 requirements.txt，也拥抱现代的 pyproject.toml。你可以逐步迁移，没有负担。
4. 设计简洁：没有过多抽象概念。如果你会用 pip，就能毫无障碍地上手 uv 的大部分功能。

七、进阶提示

• 与 IDE 配合：在 PyCharm 或 VSCode 中，只需将解释器路径指向 uv 创建的虚拟环境（通常位于 项目目录/.venv 下）即可。
• 用于 CI/CD：uv 的极速安装特性在 GitHub Actions 等 CI 环境中能显著缩短构建时间。
• 离线模式：uv 对缓存有良好的支持，适合离线或内网环境。

结语

Python 的世界正在向现代化演进，pyproject.toml 正在成为标准。uv 在这个时间点出现，像一位带着最优解的技术伙伴。它没有试图颠覆什么，而是用惊人的工程效率和简洁的设计，把那些繁琐、缓慢的事情一次性做好了。

如果你是 Python 新手，我建议你从 uv 开始，它能让你避开很多“历史坑”。如果你是老手，不妨试试 uv，那种流畅的速度感，很可能让你再也回不去。

正如软件开发中的一句老话：“最好的工具，是那个让你感觉不到存在的工具。” uv 正在朝着这个方向大步迈进。

技术不是用来炫耀的，而是用来解决问题的。uv 解决的就是“等待”和“混乱”这两个最普通又最恼人的问题。—— 模仿阮一峰/廖雪峰的语气

（本篇教程基于 uv 0.4.x 版本，其发展迅速，请关注官方文档以获取最新特性。）

参考链接：

• uv 官方网站
• uv GitHub 仓库