UV

概述

参考：

• GitHub 项目，astral-sh/uv

只需要一个二进制文件即可使用！具有缓存管理依赖库的功能，完美解决 多版本依赖、Python 虚拟环境重复安装依赖占用空间、etc. 问题。

uv init 初始化项目，生成 pyproject.toml 文件

uv add XXX 添加依赖库，同时更新 pyproject.toml 中的依赖部分

uv sync 根据 pyproject.toml 同步依赖

uv tool install XXX 以工具的形式安装 XXX。不作为依赖库

uv sync --index "https://mirrors.aliyun.com/pypi/simple/" 使用 –index 指定镜像源

uv 关联文件与配置

缓存的储存目录

• Windows: %LOCALAPPDATA%\uv\cache\
• Unix: $XDG_CACHE_HOME/uv/ 或 $HOME/.cache/uv/

[!Note] 缓存的储存目录可以通过如下几种方式修改：

• UV_CACHE_DIR 环境变量
• pyproject.toml 文件中的 tool.uv.cache-dir 键
• uv CLI 的 --cache-dir 标志

缓存

https://docs.astral.sh/uv/reference/settings/#link-mode

UV 提供四种缓存模式

• clone # 将 Packet 从缓存克隆（i.e. 写时复制）到目标
• copy # 将 Packet 从缓存复制到目标
• hadrlink # 将 Packet 从缓存硬连接到目标
• symlink # 用 Symbolic link 将 Packet 从缓存软链接到目标

Unix-like OS 上默认使用 clone 模式，Microsoft OS 上默认使用 hardlink 模式。官方不建议使用 symlink 模式

这四种模式，只有 copy 是会消耗双倍磁盘空间的，其他三种方式，基本上只有缓存中的文件才会占用磁盘空间。

[!Note]

从 文件管理 可知，hardlink 要求两个文件必须在同一个文件系统下。也就是说 Windows 下，“Python 项目” 与 “UV 缓存” 必须在同一个分区中。否则会出现提示: warning: Failed to hardlink files; falling back to full copy.

缓存模式配置方式

• 环境变量 UV_LINK_MODE
• pyproject.toml 文件中的 tool.uv.link-mode 键
• CLI 使用 --link-mode 参数

其他

uv cache clean 清除缓存

uv cache prune 会删除所有未使用的缓存条目

最佳实践

通过 pyproject.toml 配置指定的 index 以安装 CUDA 版的 torch

[project]
name = "python-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    # 加速器，用于在 GPU 上运行模型。device_map="auto"
    "accelerate>=1.13.0",
    "numpy>=2.3.1",
    "torch>=2.7.1",
    "torchvision>=0.26.0",
    "transformers>=5.3.0",
]

[[tool.uv.index]]
name = "aliyun"
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch-cu128" }
torchvision = { index = "pytorch-cu128" }

index.name 为 index 指定名称，以便其他配置使用

index.explicit 设为 true 后，这个 index 只有在 sources 字段中配置的包才可以使用。

sources 指定 torch 和 torchvision 两个包从 名为 pytorch-cu128 的 index 中获取

WSL 中使用 Windows 的缓存

让 WSL 里的 Python 使用 windows 上的 uv 缓存

sudo tee /etc/profile.d/python.sh > /dev/null <<EOF
export UV_CACHE_DIR=/mnt/d/appdata/uv/cache-linux
EOF

同时，保证 pyproject.toml 配置中使用 hardlink。

虽然 hardlink 是给 Windows 用的，但是 wsl 里也可以使用。效果不错，不会占用额外的空间了。

[tool.uv]
link-mode = "hardlink"