这是一个 uv 的使用指南。

什么是 uv?

uv 是一个由 Astral 公司推出的用 Rust 编写的一个很新的 Python 依赖管理工具，其最大特点在于速度极快、功能全面且易于上手。

uv 的目标是成为“Python 的 Cargo”，为开发者提供一个统一的端到端项目管理解决方案，所以基本上可以搞定跟 Python 环境相关的大部分工具。

简单来说，他可以代替 venv 和 Poetry 来帮你管理 Python 项目，可以代替 pyenv 和 conda 帮你管理 Python 版本，代替 pipx 做Python 全局工具的功能，而且非常快。另外，提供 pip 的界面，可以作为 pip 的直接替代品，也可以生成 requirements.txt 给其他工具用。

uv 最开始只是一个 pip 的替代品，不过现在已经扩展到很多方面去了。

uv 的功能包括:

  • 🚀 一个工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等多个工具。
  • ⚡️ 比 pip 快 10-100 倍。
  • 🗂️ 提供全面的项目管理，使用统一的锁文件。
  • ❇️ 运行脚本，支持内联依赖元数据。
  • 🐍 安装和管理 Python 版本。
  • 🛠️ 运行和安装以 Python 包形式发布的工具。
  • 🔩 包含与 pip 兼容的接口，提供熟悉的命令行界面和性能提升。
  • 🏢 支持类似 Cargo 的工作空间，适用于可扩展项目。
  • 💾 磁盘空间利用率高，通过全局缓存实现依赖项去重。
  • ⏬ 无需安装 Rust 或 Python，可通过 curl 或 pip 直接安装。
  • 🖥️ 支持 macOS、Linux 和 Windows。

如果你听过 Rye 的话，uv 算是 Rye 的继承项目，把 Rye 吃掉啦。

我在我的开源项目，Open-LLM-VTuber 的 v1.0.0 版本重构中，从 pip 迁移到了 uv，并感觉很爽。如果你也感兴趣的话可以往下读。我个人认为 uv 的使用门槛并不高，不过这是一个比较新的工具，相关文章没有特别多。

安装 uv

官方文档

安装 uv 的方式很多。

你可以使用 uv 的官方安装脚本来安装 uv。对于 macOS 和 Linux 用户, 运行

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

对于 Windows 用户，运行

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

对于用安装脚本安装 uv 的用户，可以使用一下命令更新 uv。

1
uv self update

除了安装脚本之外，你也可以

  • 使用 PyPI 来安装。可以用 pipx: pipx install uv，也可以用 pip: pip install uv
  • 使用 Cargo 来安装。cargo install --git https://github.com/astral-sh/uv uv
  • 使用 HomeBrew 来安装。brew install uv
  • 使用 WinGet 来安装。winget install --id=astral-sh.uv -e
  • 使用 Scoope 来安装。scoop install main/uv
  • 在 Docker 中使用

更详细的信息可以参考 官方文档

uv 项目管理

你可以用 uv 来管理 Python 项目的依赖，替代 pip，venv，poetry 之类的工具。

uv 遵循 PEP 518 (2016), PEP 621 (2020) 和 PEP 660 (2021) 定义的 pyproject.toml 来管理 Python 项目的依赖和元数据。

使用 uv init 命令来初始化项目。

1
uv init

初始化之后，项目目录大概会长这样

1
2
3
4
5
6
.git
.gitignore
.python-version
README.md
main.py
pyproject.toml

其中最核心的，就是这个 pyproject.toml 文件。项目的元数据和依赖都会写在里面。

pyproject.toml 文件大概长这样:

1
2
3
4
5
6
7
8
9
10
11
12
13
[project]

name = "uv-test"

version = "0.1.0"

description = "Add your description here"

readme = "README.md"

requires-python = ">=3.13"

dependencies = []

你可以在这个文件中指明项目的版本，项目的 Python 范围，依赖以及依赖的版本以及其他信息。这个文件基本就代替了 requirements.txt 和 setup.py 文件，uv 也可以生成 requirements.txt 方便其他工具使用，不过 pyproject.toml 是 Python 的标准，大部分工具应该也支持使用 pyproject.toml。

添加/移除依赖项

使用 uv add 命令来安装项目依赖。

uv add 会从 PyPi 上下载依赖，安装的依赖会写入到 pyproject.toml 文件中，并且被安装到当前目录下的 .venv 虚拟环境中。

如果当前目录下没有虚拟环境，uv 会帮你建一个。如果 Python 版本没选定，他会帮你选一个。如果没安装 Python，他会帮你装一个。

安装完成后，pyproject.toml 现在变成了这样。

用 uv remove 可以移除依赖项。

安装在 uv 虚拟环境中的依赖项，如果有命令行界面，可以直接用 uv run 运行。比如，我们刚刚安装了 ruff，这是一个 Python 代码格式化工具，我们就可以用 uv run ruff 来执行这个命令。

uv run main.py 可以使用 uv 来执行 Python 代码 (main.py 为例)。这个命令会带上虚拟环境。