如何通过pyproject.toml配置uv,锁定PyTorch(+cu118)到自定义索引并避免uv run使用CPU-only版本
如何通过pyproject.toml配置uv,锁定PyTorch(+cu118)到自定义索引并避免uv run使用CPU-only版本
嘿,我之前也踩过uv run自动拉取CPU版PyTorch的坑,折腾了好一会儿才摸透正确的配置方式。核心思路就是在pyproject.toml里明确告诉uv:PyTorch全家桶(torch、torchvision、torchaudio)必须从PyTorch的自定义cu118索引拉取,而且要锁定对应版本范围,彻底阻断它去默认PyPI找CPU版的路径。
下面直接上最稳妥的完整配置,然后我再逐个解释关键部分:
[project] name = "your-project-name" version = "0.1.0" dependencies = [ # 锁定PyTorch版本到2.7.x系列(对应你已安装的cu118版本),避免自动升级到2.8.0+cpu "torch>=2.7.1,<2.8.0", "torchvision>=0.18.1,<0.19.0", # 要和torch版本严格匹配,cu118的vision版本与2.7.x的torch绑定 "torchaudio>=2.7.1,<2.8.0", # 同理,audio版本也要和torch对齐 ] [[tool.uv.resolution.indexes]] # 指定只对PyTorch相关包使用自定义cu118索引 packages = ["torch", "torchvision", "torchaudio"] # 绑定PyTorch的cu118专属索引 url = "https://download.pytorch.org/whl/cu118" # 设置为"only",意思是这些包只能从这个索引查找,完全不碰默认PyPI priority = "only" # 双重保险:直接硬指定每个包的版本范围与专属索引,避免uv解析逻辑抽风 [[tool.uv.dependency-overrides]] torch = { version = ">=2.7.1,<2.8.0", index = "https://download.pytorch.org/whl/cu118" } torchvision = { version = ">=0.18.1,<0.19.0", index = "https://download.pytorch.org/whl/cu118" } torchaudio = { version = ">=2.7.1,<2.8.0", index = "https://download.pytorch.org/whl/cu118" }
关键配置细节拆解
版本范围锁定:
我把版本锁死在>=2.7.1,<2.8.0,就是为了防止uv解析时自动跳到你遇到的2.8.0+cpu版本。PyTorch的cu118索引里的版本号和默认PyPI是对齐的(cu118包会带+cu118后缀),锁定大版本后,uv只会从自定义索引里找符合范围的GPU版包。专属索引强制绑定:
[[tool.uv.resolution.indexes]]是核心配置——指定PyTorch全家桶只能从cu118索引获取,priority = "only"直接切断了uv去默认PyPI找CPU版的路径,从根源上解决依赖解析跑偏的问题。依赖覆盖的双重保险:
加[[tool.uv.dependency-overrides]]是怕uv偶尔出现解析逻辑的小bug,直接硬指定每个包的版本范围和专属索引,相当于给配置上了双保险,确保万无一失。
配置后的验证步骤
配置完先别急着跑脚本,先做这两步验证:
- 清理uv缓存,避免残留的CPU版包干扰:
uv cache clean - 检查依赖是否正确绑定到cu118版本:
正常输出里应该能看到版本带uv pip show torch+cu118后缀,来源路径指向cu118索引。 - 最后跑你的脚本确认:
这时候应该会加载2.7.1+cu118版本,CUDA available会显示True。uv run python test_gpu.py
额外注意事项
- 三个PyTorch包的版本必须严格匹配,它们是强绑定关系,版本不匹配不仅会出GPU问题,还会引发其他兼容性bug。
- 后续升级PyTorch版本时,记得同步更新三个包的版本范围,并且确认对应版本在cu118索引中存在(比如升级到2.8.x的话,要改成
>=2.8.0,<2.9.0)。 - 不要在
dependencies里写死torch==2.7.1+cu118(带后缀),uv对带本地后缀的版本解析逻辑会出问题,用范围锁定+专属索引就足够让它找到正确的GPU版包。
我自己用这个配置跑了好几个GPU项目,再也没出现过uv run自动拉取CPU版的情况,你可以放心用~




