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可用性验证。