uv常用命令

uv 是一个用 Rust 编写的超快 Python 包安装程序和解析器，旨在替代 pip 和 pip-tools。它提供了闪电般的安装速度和强大的依赖解析能力。本文将总结 uv 的常用命令、语法和一些使用经验。

安装 uv#

首先，你需要安装 uv。最简单的安装方式是通过 pipx：

1
pipx install uv

如果你已经安装了 uv，确保它是最新版本：

1
uv self update

常用命令#

1. 创建和管理虚拟环境#

uv 可以非常快速地创建和管理虚拟环境，这在 Python 项目开发中是必不可少的。

1
# 在当前目录创建虚拟环境
2
uv venv
3

4
# 在指定目录创建虚拟环境
5
uv venv .venv
6

7
# 指定 Python 解释器
8
uv venv --python python3.11

激活虚拟环境：

1
# macOS/Linux
2
source .venv/bin/activate
3

4
# Windows
5
.venv\Scripts\activate

2. 安装包#

uv install 命令用于安装 Python 包，它的速度比 pip install 快得多。

1
# 安装单个包
2
uv install requests
3

4
# 安装多个包
5
uv install numpy pandas
6

7
# 从 requirements.txt 安装
8
uv install -r requirements.txt
9

10
# 安装开发依赖 (例如，在 pyproject.toml 中定义为 [project.optional-dependencies] 或 dev-requirements.txt)
11
uv install --dev

3. 添加依赖#

uv add 命令可以将一个依赖添加到 pyproject.toml 文件中，并同时安装它。

1
# 添加单个包
2
uv add requests
3

4
# 添加多个包
5
uv add numpy pandas
6

7
# 添加为开发依赖
8
uv add --dev pytest

4. 卸载包#

1
# 卸载单个包
2
uv uninstall requests
3

4
# 卸载多个包
5
uv uninstall numpy pandas

5. 升级包#

1
# 升级单个包
2
uv update requests
3

4
# 升级所有已安装的包
5
uv update

6. 同步环境#

uv sync 命令会根据 requirements.txt 或 pyproject.toml 来同步你的虚拟环境，确保安装的包与文件定义的一致。

1
# 根据 requirements.txt 同步
2
uv sync
3

4
# 根据 pyproject.toml 同步
5
uv sync --dev # 如果你的开发依赖在 pyproject.toml 中

7. 冻结依赖 (生成 requirements.txt)#

uv freeze 可以生成当前环境中已安装包的 requirements.txt 文件，类似于 pip freeze。

1
uv freeze > requirements.txt

8. 编译依赖 (生成 requirements.txt.lock)#

uv compile 命令是 uv 的一个强大功能，它能解析并编译你的依赖图，生成一个锁文件 (例如 requirements.txt.lock 或 pyproject.toml 中的 uv 部分)，确保每次安装都能获得完全相同的依赖版本。

1
# 从 requirements.in 编译到 requirements.txt
2
uv compile -r requirements.in -o requirements.txt
3

4
# 从 pyproject.toml 编译
5
uv compile
6

7
# 编译开发依赖
8
uv compile --dev

通常，requirements.in 包含你直接依赖的包，而 requirements.txt (或 requirements.txt.lock) 则包含所有精确到版本的传递依赖。

9. 检查包#

1
# 检查环境中已安装的包
2
uv pip list
3

4
# 检查可用的包信息
5
uv pip show requests

特殊包的安装注意事项#

安装 PyTorch#

由于许多 PyTorch 的 wheel 文件不在 PyPI 上，安装 PyTorch 时需要一些额外的配置。

推荐通过命令行参数 --index-url 来指定索引：

1
uv pip install torch --index-url https://download.pytorch.org/whl/cpu

同时uv 还提供了一个方便的标志 --torch-backend 来自动检测加速器：

1
uv pip install torch --torch-backend=auto

使用经验与技巧#

结合 pyproject.toml 和 uv compile: 推荐使用 pyproject.toml 来管理项目的直接依赖，并利用 uv compile 来生成一个精确的锁文件。这样可以确保团队成员和 CI/CD 环境中依赖的一致性。
替代 pip-tools: 如果你之前使用 pip-compile 和 pip-sync，uv compile 和 uv sync 是更好的替代品，速度更快，功能更强大。
快速开发体验: uv 的极速安装能显著提升开发效率，尤其是在频繁创建新环境或处理大型依赖图时。
清晰的错误信息: uv 在处理依赖冲突时通常会提供比 pip 更清晰、更有帮助的错误信息。

uv 作为新一代的 Python 包管理工具，凭借其卓越的性能和强大的功能，正在迅速获得社区的关注。掌握这些常用命令，将大大提高你的 Python 项目管理效率。