uv 使用 PyTorch 指南：从 CPU 到 CUDA、ROCm 与 Intel GPU 的加速器感知配置

uv 使用 PyTorch 指南：从 CPU 到 CUDA、ROCm 与 Intel GPU 的加速器感知配置

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv

本文基于 uv 官方文档docs/guides/integration/pytorch.md，系统讲解如何用 uv 管理 PyTorch 项目：如何按平台与加速器（CPU-only、CUDA、ROCm、Intel GPU）选择并固定 PyTorch 索引、如何用环境标记与 optional dependencies 表达多环境策略，以及--torch-backend=auto自动后端选择的底层检测机制。读完后，你可以为任意平台组合编写可复制、可锁定的pyproject.toml配置，并理解 uv 在源码层面如何决定“给这台机器装哪个 PyTorch”。

需要说明的适用前提：文档指出，文中部分功能要求 uv 版本 0.5.3 或更高，建议在配置 PyTorch 前先升级 uv；此外，--torch-backend选项在 CLI 源码 中被标注为 preview（预览特性），未来版本中可能发生变化。

PyTorch 的打包特性：为什么需要特殊配置

从打包角度看，PyTorch 有几个不寻常的特点（引自 docs/guides/integration/pytorch.md）：

• 大量 wheel 托管在专属索引上，而不是 PyPI。安装 PyTorch 通常需要为项目配置 PyTorch 索引。
• 每个加速器（CPU-only、CUDA 等）对应独立的构建。由于发布和安装时没有标准化的加速器指定机制，PyTorch 把加速器编码在本地版本说明符（local version specifier）中，因此版本看起来像2.11.0+cpu、2.11.0+cu130。
• 不同加速器的构建发布在不同索引上。例如+cpu构建发布在https://download.pytorch.org/whl/cpu，+cu130构建发布在https://download.pytorch.org/whl/cu130。

因此，所需的打包配置取决于你要支持的平台和要启用的加速器。

默认配置：PyPI 上的 PyTorch

最简单的情形由uv init --python 3.14后运行uv add torch torchvision生成。此时 PyTorch 从 PyPI 安装，而 PyPI 托管的是 Windows 与 macOS 上的 CPU-only wheel，以及 Linux 上的 GPU 加速 wheel（截至 PyTorch 2.11.0，针对 CUDA 13.0）：

[project] name = "project" version = "0.1.0" requires-python = ">=3.14" dependencies = [ "torch>=2.11.0", "torchvision>=0.26.0", ]

这是一个合法的起点：Windows 和 macOS 上使用 CPU 构建，Linux 上使用 CUDA 构建。但如果你需要支持其他平台组合或加速器，就需要按下面的方式显式配置项目。

在项目中指定 PyTorch 索引

若想在所有平台统一使用某个 PyTorch 变体（例如在 Linux 上也要用 CPU-only 构建），第一步是把对应的 PyTorch 索引写入pyproject.toml。官方文档给出的各变体索引如下：

以 CUDA 13.0 为例，索引声明为：

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

官方推荐explicit = true，确保该索引只用于torch、torchvision等 PyTorch 相关包，而jinja2这类通用依赖仍从默认索引（PyPI）解析。

第二步，用[tool.uv.sources]把torch和torchvision指向目标索引。不同变体需要不同的环境标记（marker），原因如下：

• CPU-only：所有平台都适用，不需要 marker：

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

• CUDA 11.8 / 12.6 / 12.8 / 13.0：PyTorch 不为 macOS 发布 CUDA 构建，因此用sys_platform限制索引只作用于 Linux 和 Windows，macOS 回落到 PyPI（macOS 的 PyPI wheel 即 CPU 版）：

[tool.uv.sources] torch = [ { index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }, ] torchvision = [ { index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }, ]

• ROCm 7.2：PyTorch 不为 macOS 或 Windows 发布 ROCm 构建，marker 只保留 Linux；并且 ROCm 支持依赖两个 Triton 包，它们也必须从 PyTorch 索引安装（同时列入project.dependencies）：

[tool.uv.sources] torch = [ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" }, ] torchvision = [ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" }, ] # ROCm support relies on both Triton packages, which should also be installed from # the PyTorch index (and included in `project.dependencies`). pytorch-triton-rocm = [ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" }, ] triton-rocm = [ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" }, ]

• Intel GPU：PyTorch 不为 macOS 发布 Intel GPU 构建，marker 限制在 Linux 与 Windows；Intel GPU 支持依赖triton-xpu，同样要从 PyTorch 索引安装：

[tool.uv.sources] torch = [ { index = "pytorch-xpu", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }, ] torchvision = [ { index = "pytorch-xpu", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }, ] # Intel GPU support relies on `triton-xpu`, which should also be installed from the PyTorch index # (and included in `project.dependencies`). triton-xpu = [ { index = "pytorch-xpu", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }, ]

完整示例：所有平台使用 CPU-only 构建

把索引声明与 sources 组合起来，一个完整项目如下：

[project] name = "project" version = "0.1.0" requires-python = ">=3.14.0" dependencies = [ "torch>=2.11.0", "torchvision>=0.26.0", ] [tool.uv.sources] torch = [ { index = "pytorch-cpu" }, ] torchvision = [ { index = "pytorch-cpu" }, ] [[tool.uv.index]] name = "pytorch-cpu" url = "https://download.pytorch.org/whl/cpu" explicit = true

用环境标记按平台配置加速器

常见需求是：在 macOS 和 Windows 上用 CPU-only 构建，在 Linux 上用 CUDA 构建。tool.uv.sources允许对同一个包列出多条带 marker 的索引来源，uv 会按 marker 在锁定时选择生效的一条。下面的配置让 Linux 使用 CUDA 13.0，其他平台使用 CPU-only：

[project] name = "project" version = "0.1.0" requires-python = ">=3.14.0" dependencies = [ "torch>=2.11.0", "torchvision>=0.26.0", ] [tool.uv.sources] torch = [ { index = "pytorch-cpu", marker = "sys_platform != 'linux'" }, { index = "pytorch-cu130", marker = "sys_platform == 'linux'" }, ] torchvision = [ { index = "pytorch-cpu", marker = "sys_platform != 'linux'" }, { index = "pytorch-cu130", marker = "sys_platform == 'linux'" }, ] [[tool.uv.index]] name = "pytorch-cpu" url = "https://download.pytorch.org/whl/cpu" explicit = true [[tool.uv.index]] name = "pytorch-cu130" url = "https://download.pytorch.org/whl/cu130" explicit = true

同理，下面的配置让 Linux 使用 AMD GPU（ROCm 7.2）构建，Windows 与 macOS 通过回落 PyPI 获得 CPU 构建。注意 ROCm 场景下 Triton 依赖包也必须写入dependencies并钉到 ROCm 索引：

[project] name = "project" version = "0.1.0" requires-python = ">=3.14.0" dependencies = [ "torch>=2.11.0", "torchvision>=0.26.0", "pytorch-triton-rocm>=3.5.1 ; sys_platform == 'linux'", "triton-rocm>=3.6.0 ; sys_platform == 'linux'", ] [tool.uv.sources] torch = [ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" }, ] torchvision = [ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" }, ] pytorch-triton-rocm = [ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" }, ] triton-rocm = [ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" }, ] [[tool.uv.index]] name = "pytorch-rocm" url = "https://download.pytorch.org/whl/rocm7.2" explicit = true

对于 Intel GPU 构建，把 ROCm 相关部分替换为 XPU 即可：

[project] name = "project" version = "0.1.0" requires-python = ">=3.14.0" dependencies = [ "torch>=2.11.0", "torchvision>=0.26.0", "triton-xpu>=3.7.0 ; sys_platform == 'win32' or sys_platform == 'linux'", ] [tool.uv.sources] torch = [ { index = "pytorch-xpu", marker = "sys_platform == 'win32' or sys_platform == 'linux'" }, ] torchvision = [ { index = "pytorch-xpu", marker = "sys_platform == 'win32' or sys_platform == 'linux'" }, ] triton-xpu = [ { index = "pytorch-xpu", marker = "sys_platform == 'win32' or sys_platform == 'linux'" }, ] [[tool.uv.index]] name = "pytorch-xpu" url = "https://download.pytorch.org/whl/xpu" explicit = true

用可选依赖（extra）切换加速器

有时希望由使用者在同步时决定装哪个变体，例如uv sync --extra cpu与uv sync --extra cu130。tool.uv.sources支持 extra marker，可为每个启用的 extra 指定不同的索引：

[project] name = "project" version = "0.1.0" requires-python = ">=3.14.0" dependencies = [] [project.optional-dependencies] cpu = [ "torch>=2.11.0", "torchvision>=0.26.0", ] cu130 = [ "torch>=2.11.0", "torchvision>=0.26.0", ] [tool.uv] conflicts = [ [ { extra = "cpu" }, { extra = "cu130" }, ], ] [tool.uv.sources] torch = [ { index = "pytorch-cpu", extra = "cpu" }, { index = "pytorch-cu130", extra = "cu130" }, ] torchvision = [ { index = "pytorch-cpu", extra = "cpu" }, { index = "pytorch-cu130", extra = "cu130" }, ] [[tool.uv.index]] name = "pytorch-cpu" url = "https://download.pytorch.org/whl/cpu" explicit = true [[tool.uv.index]] name = "pytorch-cu130" url = "https://download.pytorch.org/whl/cu130" explicit = true

这里的关键点是[tool.uv].conflicts：它声明cpu与cu130两个 extra 互斥，避免 uv 在锁定时把两个互相冲突的索引策略同时解析进同一环境。

官方文档特别提醒：由于 GPU 加速构建在 macOS 上不可用，上面的配置在启用cu130extra 时于 macOS 上会安装失败——这正是 expected 的行为，也是为什么跨平台团队更推荐上一节的 marker 方案。

安装启用 GPU 的 PyTorch 扩展

PyTorch 生态中许多包带有针对特定 CUDA 与 PyTorch 版本组合编译的 GPU 扩展。从源码构建这类包通常需要 CUDA 开发工具链和额外的构建配置，成本很高。

Astral 提供的 GPU 索引（Astral GPU indexes）为flash-attn、deepspeed、deep-gemm、torch-scatter、vllm等包提供预构建 wheel，覆盖多种 Python、CUDA 与 PyTorch 版本组合。要为 CUDA 12.8 安装flash-attn，运行：

$ uv add flash-attn --index astral-cu128=https://wheels.astral.sh/simple/cu128/

该命令会把flash-attn加入项目依赖、配置 Astral GPU 索引，并把flash-attn固定到该索引，等价于生成如下配置：

[tool.uv.sources] flash-attn = { index = "astral-cu128" } [[tool.uv.index]] name = "astral-cu128" url = "https://wheels.astral.sh/simple/cu128/" explicit = true

与 PyTorch 索引一样，设置explicit = true可将 Astral GPU 索引限制在显式钉到它的包上，避免“污染”其他依赖的解析。

注意 Astral GPU 索引的 wheel 命名规则：每个索引针对特定 CUDA 版本，wheel 针对特定 PyTorch 版本构建。例如本地版本为+cu.12.8.torch.2.11的 wheel 对应 CUDA 12.8 与 PyTorch 2.11。选择索引和 wheel 时，要匹配你自己的 Python 版本、平台、CUDA 版本和已安装的 PyTorch 版本。具体可用包、CUDA 版本与 PyTorch 版本列表，可查阅 Astral GPU indexes 站点（配置中引用的https://wheels.astral.sh/simple/cu128/即该站点的一个端点）。

uv pip接口下的 PyTorch 安装

前面所有示例都基于 uv 的项目接口（uv lock、uv sync、uv run等），但 PyTorch 同样可以通过uv pip接口安装。

PyTorch 官方提供按目标配置生成 pip 命令的界面。例如在 Linux 上安装稳定版 CPU-only PyTorch 的标准命令是：

$ pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

用 uv 时，只需把pip3换成uv pip：

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

自动后端选择：--torch-backend=auto

除了手工配置索引，uv 还支持自动选择适当的 PyTorch 索引，通过--torch-backend=auto命令行参数或UV_TORCH_BACKEND=auto环境变量启用：

$ # With a command-line argument. $ uv pip install torch --torch-backend=auto $ # With an environment variable. $ UV_TORCH_BACKEND=auto uv pip install torch

启用后，uv 会查询已安装的 CUDA 驱动、AMD GPU 版本和 Intel GPU 的存在性，然后为所有相关包（如torch、torchvision等）选用兼容性最好的 PyTorch 索引；如果未发现任何 GPU，则回落到 CPU-only 索引。对于 PyTorch 生态之外的包，uv 仍继续尊重已有的索引配置。

也可以直接指定某个后端，例如 CUDA 13.0，用--torch-backend=cu130（或UV_TORCH_BACKEND=cu130）：

$ # With a command-line argument. $ uv pip install torch torchvision --torch-backend=cu130 $ # With an environment variable. $ UV_TORCH_BACKEND=cu130 uv pip install torch torchvision

按文档说明，--torch-backend目前仅在uv pip接口中可用。

源码级剖析：uv 如何决定 PyTorch 索引

uv 的自动后端选择由独立 crate uv-torch 实现，其定位就是“根据操作系统和 CUDA 驱动版本决定合适的 PyTorch 索引”（实现源自 light-the-torch 项目，见 backend.rs 的文件头注释）。

1. 后端取值范围远大于文档表格。TorchMode 枚举 定义了auto、cpu、CUDA 13.2 到 CUDA 10.0 的各版本（cu132、cu130、cu129、cu128、cu126一路到cu80）、ROCm 7.2 到 4.0.1 的各版本（rocm7.2、rocm7.1、rocm6.4……）以及xpu。也就是说，CLI 接受的后端值比文档表格列出的那几个更完整，文档表格只展示了常用的几个。

2.auto模式的硬件探测顺序。探测逻辑在 accelerator.rs 中，Accelerator::detect的文档注释列出了严格的查询优先级：

1. UV_CUDA_DRIVER_VERSION环境变量覆盖值；
2. UV_AMD_GPU_ARCHITECTURE环境变量覆盖值；
3. /sys/module/nvidia/version（NVIDIA 驱动版本，如550.144.03）；
4. /proc/driver/nvidia/version；
5. nvidia-smi --query-gpu=driver_version --format=csv,noheader；
6. rocm_agent_enumerator（列出 AMD GPU 架构，如gfx906）；
7. /sys/bus/pci/devices，按 PCI 厂商号0x8086（Intel）与显示类码过滤出 Intel GPU；
8. Windows 设备树，按 PCI 过滤已安装的 Intel 显示适配器。

值得注意的是这里检测的是CUDA 驱动版本（如550.144.03）而非 CUDA 工具包版本（如12.8.0）——源码注释明确区分了两者（见 accelerator.rs）。index_urls 方法 随后根据操作系统把驱动版本映射为索引列表：Linux 上按驱动版本从高到低筛出所有满足driver_version >= 最低要求的 CUDA 索引，最后总是追加 CPU-only 索引作为兜底；Windows 逻辑相同；macOS 及其他平台只给出 CPU-only 索引。这解释了为什么文档中反复强调“macOS 回落 PyPI”——自动模式下 macOS 根本不会产生 CUDA 索引。

3. “相关包”的边界由源码固定。TorchStrategy::applies_to 硬编码了自动策略作用的包名清单：torch、torchvision、torchaudio、torchtext、torchtune、torchao、torchrec、fbgemm-gpu、triton、triton-rocm、triton-xpu、xformers等；has_system_dependency 进一步区分哪些包（如torch、flash-attn、vllm）与 CUDA/ROCm 版本存在系统级依赖——例如cu128索引上的triton并不依赖 CUDA 12.8，因此它被排除在“系统依赖”之外。这与文档中“uv 会为所有相关包使用同一索引，同时继续尊重生态外包的既有配置”的描述一一对应。

4. 参数在 pip 接口中的接线。--torch-backend在 uv-cli 中定义为PipCompileArgs的参数，并绑定环境变量UV_TORCH_BACKEND；从源码结构看，pip 系列的多个子命令（pip compile、pip sync、pip install，见 lib.rs 中的 L2209、L2561）都携带该参数，与文档“目前仅在uv pip接口可用”的说明一致。参数帮助文本还指出：设置该选项后，uv 会忽略PyTorch 生态包已配置的索引 URL，转而使用所选后端——即它优先于tool.uv.index配置，这正是自动选择与手工配置两套机制的优先级关系。

小结与延伸阅读

• 默认（不配置索引）时，PyTorch 从 PyPI 安装：Windows/macOS 得到 CPU 构建，Linux 得到 CUDA 构建；
• 需要统一变体时，用[[tool.uv.index]]（explicit = true）+[tool.uv.sources]把torch、torchvision（以及 ROCm/XPU 场景下的 Triton 包）钉到指定索引，CUDA/ROCm/XPU 记得按平台加sys_platformmarker；
• 需要按平台分流时用环境标记，需要按用户选择切换时用 optional dependencies 加conflicts声明互斥；
• GPU 扩展包（flash-attn、vllm等）可用 Astral GPU 索引的预构建 wheel，免去本地 CUDA 编译；
• 在uv pip接口下可用--torch-backend=auto或UV_TORCH_BACKEND让 uv 根据本机 GPU 自动选索引。

进一步阅读：

• 本文档原型：docs/guides/integration/pytorch.md
• 自动后端选择实现：crates/uv-torch/src/backend.rs、crates/uv-torch/src/accelerator.rs
• 参数定义与说明：crates/uv-cli/src/lib.rs
• 索引与 sources 的 schema 定义见 uv.schema.json

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv