uv：高效 Python 包管理工具入门指南

uv 是一个用 Rust 编写的高速 Python 包解析器和包管理工具。它旨在成为替代 pip、pip-tools、virtualenv、conda 等工具的单一、统一工具。

1. Python 与 Virtual Environment (虚拟环境) 的关系

为什么需要虚拟环境？

Python 的一个常见问题是项目间的依赖冲突。想象一下：

• 你正在开发项目 A，它需要 requests v2.25.0。
• 你又开始开发项目 B，它需要 requests v3.0.0。
• 你的全局 Python 环境 (python -m pip install ...) 只能安装一个版本。如果你为项目 B 升级了 requests，项目 A 就可能因为版本不兼容而无法运行。

虚拟环境就是解决这个问题的答案。

虚拟环境是一个独立的、隔离的目录，其中包含特定版本的 Python 解释器、包管理工具（如 pip）以及项目所需的第三方库。每个项目都可以拥有自己专属的虚拟环境，其中的依赖包互不干扰。

传统工作流： venv + pip

# 创建环境
python -m venv .venv

# 激活环境 (Linux/macOS)
source .venv/bin/activate
# 激活环境 (Windows)
.\.venv\Scripts\activate

# 在激活的环境中安装包
pip install requests

# 停用环境
deactivate

uv 将这个工作流极大地简化和加速。

2. uv 相对于 pip 与 conda 的优势

核心优势总结：

1. 速度： 无论是创建虚拟环境还是安装依赖包，uv 的速度都比 pip 和 conda 快一个数量级，这得益于其 Rust 实现和高并发设计。
2. 一体化： uv 将虚拟环境管理、依赖安装、依赖锁定、工具运行等功能集成在一个工具中，无需在多个命令 (venv, pip, pip-tools) 之间切换。
3. 与 PyPI 生态兼容： 它直接使用 PyPI 索引，意味着你能访问所有 pip 可用的包，没有 Conda 通道（channel）的兼容性问题。
4. 可重复性： 其 uv.lock 文件提供可重复的、精确到子依赖版本的依赖安装，非常适合 CI/CD 和部署。

简单来说，如果你主要从 PyPI 安装包，并且追求极致的速度与现代化的工作流，uv 是目前最好的选择。

3. uv venv 的构建与 .venv 路径选取

安装 uv

首先，你需要安装 uv。通常使用 curl 或 pipx 一键安装：

# 使用 curl (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者使用 pipx (跨平台，不建议)
pipx install uv

# 安装后，重启你的终端即可使用 `uv` 命令。

创建虚拟环境

使用 uv venv 命令创建虚拟环境。

基本用法：

# 在当前目录下创建名为 `.venv` 的虚拟环境
uv venv

这行命令会在当前目录创建一个 .venv 文件夹。

.venv 环境路径的选取方法：

uv venv 命令非常灵活，你可以通过参数指定环境的名称和位置。

1. 默认行为 (推荐)： 不指定名称，创建 .venv 目录。

   uv venv
   

   优势： 大多数工具（如 VS Code、PyCharm）都能自动识别项目根目录下的 .venv 目录作为虚拟环境。这是社区的事实标准。

2. 指定一个路径： 你可以将环境创建在任何位置。

   # 创建在相对路径下
   uv venv my_project_env
   
   # 创建在绝对路径下
   uv venv /path/to/custom/env
   

3. 指定 Python 解释器版本： 如果你的系统安装了多个 Python 版本，可以使用 --python 参数指定。

   uv venv --python 3.11
   uv venv --python 3.12
   # 或者指定具体的解释器路径
   uv venv --python /usr/bin/python3.9
   

激活虚拟环境

创建环境后，你需要激活它（与传统虚拟环境激活方式完全相同）：

# Linux / macOS
source .venv/bin/activate

激活后，你的命令行提示符前通常会显示环境名 (.venv)，表示你正处在该环境中。

在虚拟环境中安装依赖

激活环境后，你可以使用 uv pip install 来安装包，它与标准的 pip install 命令完全兼容但更快。

# 安装单个包
uv pip install requests

# 从 requirements.txt 安装
uv pip install -r requirements.txt

4. 使用独立环境运行工具程序 (uv tool)

这是一个非常强大的特性。通常，如果你想使用一个命令行工具（如 black, mypy, pytest），你需要先将其安装到某个虚拟环境中，再激活环境来运行。

uv tool 命令解决了这个问题。它允许你在独立、隔离的环境中全局安装和运行工具，避免污染你的全局 Python 环境或项目环境。

安装工具 (uv tool install)

# 全局安装 black 格式化工具
uv tool install ase

# 现在你可以直接在终端任何地方使用 `ase` 命令了
ase

uv 会为 ase 创建一个专门的、隔离的虚拟环境来存放它和它的依赖，然后将 ase 的可执行文件链接到一个全局位置（如 ~/.local/bin），让你可以直接在终端调用。

直接运行工具 (uv tool run 或 uvx )

如果不想安装black到PATH，而是只运行一次 uv tool run 是完美的选择。它会在一个临时的隔离环境中下载并运行该工具，运行完毕后环境会被清理。

# 临时运行 ase 来查看结构，而无需安装它
uv tool run ase gui POSCAR

# 临时使用 pytest 运行测试
uv tool run pytest

# 运行特定版本的工具
uv tool run "ase@3.26" ase convert POSCAR my.cif

这个功能的优势：

• 干净： 不会在全局或项目环境中留下任何痕迹。
• 安全： 每次运行都是隔离的，避免了依赖冲突。
• 方便： 无需预先安装，即可尝试或使用任何 CLI 工具。

作为项目管理器

上述教程主要针对使用uv管理包含多个依赖项虚拟环境。 除了管理虚拟环境，uv本身也可以用于管理Python程序包开发中的依赖管理。 Further Reading: https://docs.astral.sh/uv/guides/projects/

PyPI 加速

国内用户建议在 ~/.config/uv/uv.toml 或者 /etc/uv/uv.toml 填写下面的内容，使用清华源PyPI镜像来加速下载：

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true