Windows下PyTorch GPU环境搭建与CUDA版本匹配

脚本专家

在Windows上运行PyTorch GPU训练或推理时，最容易出问题的通常不是模型代码，而是驱动、CUDA、Python与torch三件套之间的版本对应。下面按可落地的命令和WHL命名规则，梳理从驱动检查到GPU可用性验证的完整流程。

一、检查显卡驱动支持的CUDA上限

先确认设备搭载NVIDIA独立显卡，并在cmd中执行：

2. nvidia-smi

复制代码

输出中会显示显卡型号和驱动信息，右上角会标注当前驱动可支持的最高CUDA版本。后续准备安装的CUDA Toolkit版本不能高于这个数值，否则无法正常使用；如果驱动版本过低，先前往NVIDIA官网更新显卡驱动。

二、CUDA Toolkit安装与环境变量

CUDA是NVIDIA提供的并行计算平台和编程模型，让程序能调用GPU做大规模并行计算，也是深度学习加速的基础。PyTorch安装包中的cuXXX是CUDA版本的简写标识，例如+cu124代表该包基于CUDA 12.4编译，+cu128代表基于CUDA 12.8编译。

下载CUDA Toolkit：

最新版本直达页：https://developer.nvidia.com/cuda-downloads
历史版本归档页：https://developer.nvidia.com/cuda-toolkit-archive

页面参数选择参考：Operating System选Windows，Architecture选x86_64，Version选择不超过nvidia-smi上限的版本，深度学习常用12.x系列，Installer Type选exe (local)。本地完整离线安装包大小约2~3GB。

安装时选择自定义安装Custom。如果已经装好新版显卡驱动，可以取消勾选Driver组件，只安装CUDA其余部分。默认安装路径为：

2. C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.X

复制代码

安装程序一般会自动配置环境变量。如果没有生效，手动添加：右键此电脑，进入属性、高级系统设置、环境变量，在系统变量Path中新增下面两条路径，并把v12.X替换为本机实际CUDA版本：

2. C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.X\\bin
3. C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.X\\libnvvp

复制代码

配置完成后必须重新打开新的命令行窗口，再执行：

2. nvcc --version

复制代码

正常输出会显示release X.Y版本信息，代表CUDA Toolkit安装成功。

补充说明：带+cuXXX后缀的PyTorch安装包内部已经自带运行所需的CUDA runtime运行库。如果仅用来运行PyTorch训练推理，很多场景下不需要完整安装CUDA Toolkit，只要显卡驱动版本足够即可。单独安装完整CUDA Toolkit的优势是自带nvcc编译器、cuBLAS等全套开发组件，适合自定义CUDA算子、底层GPU开发等场景。

三、看懂WHL文件名

示例文件名：

2. torch-2.10.0+cuXXX-cp3xx-cp3xx-win_amd64.whl

复制代码

关键字段含义：torch是包名，配套还有torchvision、torchaudio；2.10.0是PyTorch核心版本号；+cuXXX是GPU版本，XXX对应CUDA版本，无+cu则为CPU版本；cp3xx是适配的Python版本，如cp311代表Python3.11；win_amd64代表Windows 64位系统；.whl是Python wheel离线安装包格式。

示例版本2.10.0对应torchvision 0.25.0、torchaudio 2.10.0，安装时版本号需成套，不要混搭不同主版本号。下载whl包时，cp3xx必须和本机Python版本完全匹配，否则pip会报不支持的wheel平台错误；cuXXX要和前面nvidia-smi查询到可支持的CUDA版本匹配。

四、方法一：本地WHL安装

先访问下载地址获取whl包：打开https://download.pytorch.org/whl/cu126，依次进入torch、torchvision、torchaudio，在页面中找到匹配本机Python版本cp3xx、Windows平台的torch、torchvision、torchaudio三个whl文件并下载。

将三个whl文件放在同一个文件夹内，在该文件夹路径下打开命令行，执行安装：

2. pip install torch-2.10.0+cuXXX-cp3xx-cp3xx-win_amd64.whl
3. pip install torchvision-0.25.0+cuXXX-cp3xx-cp3xx-win_amd64.whl
4. pip install torchaudio-2.10.0+cuXXX-cp3xx-cp3xx-win_amd64.whl

复制代码

也可以一键批量安装：

2. pip install *.whl

复制代码

建议先单独安装torch，再装torchvision、torchaudio，依赖解析更稳。

五、方法二：在线安装

网络条件良好时，直接使用PyTorch官方源在线安装，将命令里的cuXXX替换为本机匹配的CUDA版本标识：

2. pip install torch==2.10.0 torchvision==0.25.0 torchaudio==2.10.0 --index-url https://download.pytorch.org/whl/cuXXX

复制代码

国内访问官方源速度慢时，可以替换国内镜像源，示例为南大镜像：

2. https://mirrors.nju.edu.cn/pytorch/whl/cuXXX

复制代码

六、安装matplotlib

当需要matplotlib绘图时，该库不属于PyTorch自带组件，需要单独安装：

2. pip install matplotlib

复制代码

七、验证环境是否部署成功

可以直接运行下面代码校验版本与GPU可用性：

2. import torch
3. import torchvision
4. import torchaudio
6. print(torch.__version__)
7. print(torchvision.__version__)
8. print(torchaudio.__version__)
9. print(torch.cuda.is_available())

复制代码

成功标准：版本号后缀带有+cuXXX，且torch.cuda.is_available()输出True，代表GPU版本PyTorch环境安装完成。

八、关键排查与版本匹配点

1. 先查驱动上限：nvidia-smi显示的CUDA版本是硬上限，安装的CUDA Toolkit不能超过它。
2. 版本成套：PyTorch、torchvision、torchaudio的版本号必须配套，如2.10.0对应0.25.0对应2.10.0，且+cuXXX后缀需一致。
3. Python版本严格匹配：WHL文件名中的cp3xx必须与当前Python解释器版本完全一致。
4. 环境变量生效：安装完CUDA后，务必重新打开命令行窗口再执行nvcc --version验证。
5. 按需选择安装方式：网络不稳定时优先选择WHL本地离线安装，速度快且可靠；网络好且熟悉版本号时可选在线安装。

以上流程覆盖驱动检查、CUDA Toolkit安装与验证、WHL命名规则、本地与在线安装、matplotlib补充依赖以及最终GPU可用性验证。

热心网友7

感谢整理，这篇对刚在Windows上配PyTorch GPU环境的人很友好。最实用的是把nvidia-smi的CUDA上限、whl里的cuXXX、cp3xx和版本成套这几件事串起来了，之前就是没注意Python版本和wheel要完全匹配，结果pip直接报平台不支持。还有个提醒很到位：只跑PyTorch训练推理的话，驱动够新就行，不一定非要完整装CUDA Toolkit，需要nvcc和底层开发再装全套更合适。最后验证看版本后缀+cuXXX和torch.cuda.is_available()为True也很直接。第八部分好像还没写完，期待后续把关键排查点补全。

热心网友5

楼主整理得很清楚，Windows 下搞 PyTorch GPU 环境最头疼的就是驱动、CUDA、Python 和 torch 之间的版本对应，尤其是 whl 文件名里那些 cp3xx、cuXXX 字段，很容易看晕。你按 nvidia-smi 查驱动上限、再选 CUDA Toolkit、然后按 whl 命名规则匹配 Python 和 CUDA 版本，最后用 torch.cuda.is_available() 验证，整个流程很顺，适合照着排查。 我自己印象最深的是装完 CUDA Toolkit 后要重新开新的命令行再执行 nvcc --version，旧窗口环境变量不生效，容易误以为装失败。另外如果只是跑 PyTorch 训练推理，确实不一定非要完整装 CUDA Toolkit，驱动版本够新就行，这点你补充得很实用。whl 三个包版本成套、先装 torch 再装 torchvision 和 torchaudio，也能少踩很多依赖坑。matplotlib 需要单独装这个细节对画图的人也有用。感谢分享，收藏备用。

热心网友2

楼主这篇整理得很细，尤其是先看 nvidia-smi 的 CUDA 上限，再按 whl 命名规则选 cp3xx 和 cuXXX，这个顺序确实能少走很多弯路。我自己也踩过装完没重开命令行、结果 nvcc 找不到的坑，所以看到你提醒重新打开窗口这点很实用。只跑 PyTorch 训练推理的话，确实不一定非要装完整 CUDA Toolkit，驱动版本够、torch 包自带 runtime 通常就能用；要自己编译 CUDA 算子再装完整 Toolkit 更合适。torch、torchvision、torchaudio 版本成套这点也很关键，混搭很容易出问题。最后用打印版本和 torch.cuda.is_available() 来验证最直接，看到 +cuXXX 和 True 基本就稳了。第八点好像没发完，期待楼主补上排查部分。