Python uv 简明教程

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

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

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

这些问题，归根结底是 Python 的包管理和项目依赖管理长期处于一种“自由散漫”的状态。pip 很好，但它只是个安装器；venv 能隔离环境，但用起来稍显繁琐；而 poetry、pdm 等现代工具又带来了新的概念。
今天，我要介绍一个全新的工具：uv。它由 Astral 公司（打造了 Ruff 这个极速的 Python linter）开发，旨在用一个二进制文件，解决从包安装到项目管理的绝大部分问题。它的核心特点是：极致的快和极致的简单。
一、uv 是什么？

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

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

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

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

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

复制代码

对于 Windows 用户（PowerShell）：

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

复制代码

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

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

1. mkdir my-awesome-app && cd my-awesome-app

复制代码

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

这是 uv 独有的便捷功能。

1. uv init

复制代码

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

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

1. uv add requests flask

复制代码

感受一下速度。你会发现安装过程几乎是瞬间完成的。uv 不仅从网络下载快，其内部的依赖解析算法也极其高效。
此时，查看你的 pyproject.toml，依赖已经被自动添加：

1. [project]
2. name = "my-awesome-app"
3. version = "0.1.0"
4. dependencies = [
5.     "requests",
6.     "flask",
7. ]

复制代码

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

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

1. # 直接运行一个命令，uv 会确保它在正确的虚拟环境中执行
2. uv run python -c "import requests; print(requests.__version__)"
4. # 或者启动一个在虚拟环境中的 Python 解释器 shell
5. uv python

复制代码

你不需要手动 source venv/bin/activate，uv run 和 uv python 帮你处理了一切，减少了上下文切换。
四、在已有项目中使用 uv

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

1. # 安装所有依赖（速度比 pip install -r requirements.txt 快一个数量级）
2. uv pip install -r requirements.txt
4. # 或者，如果你想升级到现代工作流，可以生成 lock 文件
5. uv lock --requirements-in requirements.txt --locked

复制代码

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

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

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

复制代码

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

命令作用传统等效命令uv add 添加依赖并更新 pyproject.tomlpoetry add uv sync同步依赖（安装/更新）poetry install / pip install -e .uv run 在项目虚拟环境中运行命令source venv/bin/activate && uv python启动项目虚拟环境的 Python 解释器source venv/bin/activate && pythonuv lock生成/更新 uv.lock 锁文件poetry lockuv init交互式创建 pyproject.toml手动创建uv pip compile编译 requirements.txt（高级）pip-compile六、为什么选择 uv？一个简单的总结

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

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！