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？一个简单的总结

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 仓库