1. 为什么环境配置总是头一道坎
准备深度学习环境，乍一看就是安装 CUDA、PyTorch、TorchVision、TorchAudio 这么几个东西，但实际上手时，很容易被各种版本号、报错信息、兼容性问题卡半天。尤其是 CUDA 安装配置，牵扯到显卡驱动、系统路径、编译工具链，任何一个环节对不上，后面跑训练脚本就是一串莫名其妙的问题。我见过很多朋友在模型代码上折腾两小时没结果，最后发现是 torch 根本没有调用到 GPU，或者 torchvision 版本和 torch 不匹配，导入直接崩。
这套环境之所以特别，是因为它不只是“装个软件包”那么简单。PyTorch 是一个深度学习框架，TorchVision 和 TorchAudio 是围绕它的生态库，而 CUDA 是让这些库能调用 GPU 进行并行计算的底层平台。三者互相配合，但又不完全是同一条安装链路上的东西。很多人以为装了显卡驱动就等于装了 CUDA，其实驱动、CUDA 工具包、PyTorch 自带的 CUDA 运行时是三回事，搞清楚它们的区别，环境配置的问题就解决了一大半。
这篇文章会从底层关系讲起，再到版本怎么选、命令怎么敲、验证怎么做，最后把最常踩的坑列出来。不管是第一次装环境的小白，还是被环境搞到头疼的老手，都能找到可以直接照抄的部分。安装这种事，最忌讳背命令，理解了为什么这么干，换一台机器、换一个系统，你也能自己搞定。
2. 动手前先搞明白三层依赖关系
2.1 驱动、CUDA 工具包、PyTorch 运行时
先做一个类比。显卡驱动像操作系统识别硬件的“底层驱动层”，它负责让系统能看到 GPU，并且提供最基本的调度能力。CUDA 工具包则是一套完整的开发环境，里面有编译器、调试工具、各种库文件，你可以用它来编译和开发自己的 CUDA 程序。而 PyTorch 在安装 GPU 版本时，会带上一套 CUDA 运行时组件，也就是说，它内部已经包含了一部分 CUDA 的函数库，不需要你再单独装完整的 CUDA 工具包就能跑起来。
这句话很关键：很多人以为必须手动装完 CUDA 工具包，PyTorch 才能用 GPU，其实不是。只要显卡驱动足够新，并且你装的 PyTorch 是针对某个 CUDA 版本编译好的 wheel 包，那么 torch 自己带的运行库就能直接调用 GPU。你装 CUDA 工具包，更多的是为了做两件事：一是跑nvcc去编译自定义的 CUDA 扩展，二是让系统里有一个和驱动配套的完整 CUDA 环境。
那为什么标题里还是强调“CUDA 安装配置”？因为现实情况里，很多机器没有装匹配的驱动，或者系统里已经有一版很老的 CUDA，会和 PyTorch 要求的运行库发生冲突。另外，如果你要用到自定义算子、编译源码安装某些库，没有 CUDA 工具包会直接报nvcc not found。所以稳妥的方案是：驱动一定装好，CUDA 工具包按需装，PyTorch 的安装则直接用官方提供的匹配版本，不要自己混搭。
2.2 Torch 全家桶到底有哪些分工
PyTorch 是主框架，负责张量运算、自动求导、神经网络模块等等。TorchVision 是围绕视觉任务开发的库，里面有常用的数据集、预训练模型、图像变换工具，比如 ResNet、DataSet、Transform 这些东西。TorchAudio 则是面向音频任务的库，包含音频 I/O、特征提取、常用数据集和音频模型。三者虽然功能侧重不同，但版本之间是严格绑定的。
TorchVision 和 TorchAudio 在编译时依赖特定版本的 PyTorch，所以它们的版本号并不是随意取的。PyTorch 2.1 往往对应 TorchVision 0.16、TorchAudio 2.1，PyTorch 2.2 对应 TorchVision 0.17、TorchAudio 2.2，是一一对应的关系。装的时候最省心的方式，是在同一条官方安装命令里一起装，而不是分别从不同的源装。分开装的话，很容易出现 torchvision 要求 torch>=2.1，可你装的是 2.0，导入时直接报module 'torch' has no attribute '...'之类的错误。
还有一点值得留意，这几个库的安装包名称和导入名称完全一致。pip 安装时写的是torch、torchvision、torchaudio，Python 里导入时也是这三个名字，所以安装完马上做一个导入测试非常方便。如果连导入都过不去，基本就是版本冲突；如果导入成功但cuda.is_available()是 False，那问题就出在驱动或者安装包的 CUDA 版本上。
3. CUDA 安装配置：从零到能编译
3.1 第一步先查硬件和驱动
不论你在 Windows 还是 Linux 上操作，第一步都是确认显卡型号和驱动状态。终端里运行显卡自带的状态检查命令nvidia-smi，会输出驱动版本、显存占用以及当前驱动支持的最高 CUDA 版本号。
很多人看到右上角的 CUDA Version 就以为系统里装好了 CUDA，这是个经典误区。这里显示的 CUDA 版本只是驱动的“能力上限”，意思是驱动允许你用不高于这个版本的 CUDA 工具包。它并不代表你已经安装了 CUDA 工具包，也不代表nvcc一定可用。判断工具包是否安装，要看nvcc -V的输出，那个显示的是实际安装的 CUDA 编译器版本。
如果你的驱动版本比较老，后面装完 PyTorch 可能会发现torch.cuda.is_available()返回 False，或者运行时报找不到 CUDA 驱动。这种情况首先去显卡厂商官网下载对应型号的最新驱动，不要用系统自带的通用显卡驱动，尤其是 Linux 服务器上，驱动内核模块没加载好的情况很常见。装完驱动重启一下，再跑nvidia-smi，确认驱动版本能覆盖你需要的 CUDA 版本。
3.2 CUDA 工具包到底装不装
如果你只是用 PyTorch 跑现成的模型，不自己编译 CUDA 扩展，那么最简方案是“只装驱动 + 安装 GPU 版 PyTorch”。PyTorch 官方提供的带 CUDA 后缀的 wheel 包，已经把用到的 CUDA 运行时库都打包进去了，不需要另装 CUDA 工具包。这个方案在绝大多数场景下都是最稳的，因为你少装一个组件，就少一个出错点。
但标题里既然强调了“CUDA 安装配置”，我还是建议在开发机上完整装一次工具包，原因有三点。第一，很多第三方库在安装时会尝试调用nvcc编译扩展，没有工具包直接失败。第二，nvcc是验证系统 CUDA 环境是否正常的标准工具，有它方便排查问题。第三，你以后如果要用 TensorRT、DeepSpeed 这类偏底层的工具，提前有一个完整 CUDA 开发环境会省很多事。
安装时要注意版本选择，不要盲目装最新版。PyTorch 官方镜像通常提供 cu118、cu121、cu124 这类版本标签，你要先想好自己打算用哪个版本，然后装对应的 CUDA 工具包。比如计划用 cu118，就装 CUDA 11.8；计划用 cu121，就装 CUDA 12.1。不用非得和驱动的最高支持版本一致，只要驱动支持的上限大于等于你装的工具包版本即可。
3.3 安装与配置环境变量
CUDA 工具包的安装方式根据系统而定。Windows 下是运行安装程序，选择自定义安装，不建议把全家桶都装上，只勾选 CUDA 核心组件就够。安装目录一般会放在固定的默认位置，装完以后需要手动把bin目录和lib64目录加进系统环境变量。
Linux 下常见的方式有两种：一种是系统包管理器安装，另一种是官方提供的 runfile 安装。更推荐用 runfile 方式，因为可以自定义安装目录，不污染系统里已有的 CUDA 组件，卸载时也方便。假设你把它装在/opt/cuda，那需要在~/.bashrc里添加：
export PATH=/opt/cuda/bin:$PATH export LD_LIBRARY_PATH=/opt/cuda/lib64:$LD_LIBRARY_PATH加完以后执行source ~/.bashrc让它生效。这个步骤不能省，很多情况是 CUDA 明明装好了，但因为没加环境变量，导致nvcc -V找不到命令。Windows 用户在图形界面的系统设置里添加 PATH，效果是一样的，注意把安装目录下的bin以及libnvvp之类的路径都加进去。
装完以后跑一遍nvcc -V，能看到类似release 11.8的输出，就说明 CUDA 工具包已经就绪。此时再跑一次nvidia-smi，确认驱动支持的 CUDA 版本不低于工具包版本，两者就能配合工作。这里有个细节：nvidia-smi显示的版本是动态的，如果驱动升级了，那个数字也会变。所以只要驱动版本高于工具包要求，就不用担心。
3.4 用一个小矩阵验证环境
CuDNN 是深度神经网络常用的加速库，PyTorch 的 GPU 版本一般会自带的 CUDA runtime 里捎带兼容实现，通常不需要单独装。但如果你需要手动装 CuDNN，安装完以后可以用一段 Python 代码验证 torch 是否使用 GPU：
import torch print(torch.__version__) print(torch.version.cuda) print(torch.backends.cudnn.version()) print(torch.cuda.is_available())如果有人问你，torch.version.cuda和nvcc -V显示不一样怎么办，别慌。torch.version.cuda是 PyTorch 这个 wheel 包编译时用的 CUDA 版本，它不要求等于系统 CUDA 工具包的版本。只要torch.cuda.is_available()是 True，并且 GPU 能被识别，那这俩版本不一致完全正常。
4. PyTorch、TorchVision、TorchAudio 的安装实操
4.1 先建一个干净的 Python 环境
我强烈建议在装 PyTorch 之前先用 conda 建一个独立环境，不要直接往系统 Python 里塞。深度学习依赖往往又大又互相牵连，一旦和系统包混在一起，后面想升级或删掉会很痛苦。新建环境的命令很简单：
conda create -n torch-env python=3.10 -y conda activate torch-envPython 版本选择上，PyTorch 官方目前对 3.9、3.10、3.11 这些都支持得很好。不需要刻意追求最新版，因为某些旧库对新 Python 版本的兼容还不完善。如果机器上没有 conda，也可以用python -m venv创建虚拟环境，不过 conda 的优势在于它能额外管理非 Python 的原生依赖，处理 CUDA 相关的包更方便。
环境建好以后，先确认pip版本不要太老。老版本 pip 在解析大包时会比较慢，也容易出一些网络超时问题。可以先升级一下：
python -m pip install --upgrade pip4.2 安装全家桶的标准命令
PyTorch 官方提供了一条非常标准的三件套安装命令，直接照抄即可：
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118把命令末尾的cu118换成你想要的 CUDA 版本，比如cu121、cu124，就能得到对应版本的三件套。这条命令最不容易出错的地方在于，它一次性固定了 torch、torchvision、torchaudio 的兼容版本，你不用担心某个包单独升级导致冲突。很多人图省事，直接pip install torch torchvision torchaudio从默认源装，结果默认源给出的可能是 CPU 版，或者说和你的目标 CUDA 版本不一致。所以，想要 GPU 加速，最好还是走官方给出的 index-url。
如果你需要指定版本，可以这样写：
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu118这个方式多用于复现某个项目时锁定环境版本。项目文档里写了依赖版本的，千万别自己想当然装最新版，严格按文档来。没有写明版本的，才用官方 index-url 装默认版。
4.3 安装完立刻做连通性测试
三件套装完，先跑一个最简验证脚本：
import torch import torchvision import torchaudio print("torch", torch.__version__) print("torchvision", torchvision.__version__) print("torchaudio", torchaudio.__version__) print("CUDA available:", torch.cuda.is_available()) print("GPU count:", torch.cuda.device_count())如果输出里 CUDA available 是 True，说明整个链路已经通了。接下来做一次简单的 GPU 张量运算，确保不只是库能导入，GPU 真的在干活：
import torch x = torch.randn(10000, 10000, device="cuda") y = torch.mm(x, x) print(y.sum().item())这段代码会在 GPU 上创建一个大矩阵并做乘法，如果设备分配成功，会有正常的数值输出。如果这里报CUDA error: no kernel image is available for execution on the device，那多半是显卡的算力版本太老，而你装的 PyTorch 太新，不再支持那块 GPU 了。这种情况就要考虑换成旧版 PyTorch，或者找对应旧 CUDA 的 wheel 包。
TorchVision 和 TorchAudio 也要简单测一下。比如：
import torchvision.transforms as T transform = T.Compose([T.Resize((224, 224)), T.ToTensor()]) print(transform)再比如：
import torchaudio print(torchaudio.__version__)这一步的意义在于提前暴露问题，别等到跑完整数据管线才发现库之间版本不对。
4.4 用 pip 检查依赖树
有时候安装过程显示成功，但运行时报错，很可能是某些传递依赖被其他项目覆盖了。可以用 pip 查看安装的包信息：
pip list | grep torch如果发现 torch 和 torchvision 版本不匹配，就按照官方版本对应表重新安装。还有个习惯值得养成：每次装完环境，把当前环境的版本信息记录到一个文件里：
pip freeze > requirements.txt这样以后换机器复现环境，直接一条命令就能装回来。深度学习项目最怕的就是环境和代码丢失，锁版本这个动作成本极低，收益却很高。
5. 常见问题与排查实录
5.1 torch 导入时报 Illegal instruction
这是我遇到过的比较隐晦的问题之一。PyTorch 较新版本的 CPU wheel 可能默认用了比较新的 CPU 指令集，老旧的 CPU 跑起来直接崩，报一个Illegal instruction (core dumped)。注意，这个问题和 GPU 没关系，发生在导入 torch 或做 CPU 张量运算时。解决办法一般是使用较旧的 PyTorch 版本，或者在官方论坛里确认当前 wheel 支持哪些 CPU 架构。遇到这种诡异问题时，先别怀疑代码，先用最简单张量操作定位是不是库本身的二进制兼容性问题。
5.2 torch.cuda.is_available() 返回 False
这个报错出现频率最高。排查顺序建议如下：先看nvidia-smi是否有 GPU 输出，没有就说明驱动没装好；有输出就看看驱动支持的 CUDA 版本是否大于等于你装的 PyTorch 对应的 CUDA 版本。再检查 PyTorch 是不是装成了 CPU 版，CPU 版的特征是torch.version.cuda为 None，或者安装命令里没有带 CUDA 版本后缀。最后还要检查环境变量CUDA_VISIBLE_DEVICES是否被设置为空或者不存在的设备编号，有时候是项目脚本里设置了它，导致程序里看不到 GPU。
如果这些都没问题，尝试强制重装一次匹配的 GPU 版本：
pip install --force-reinstall torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu1185.3 nvcc 找不到但 PyTorch 能正常用
之前提过，PyTorch 自带的 CUDA runtime 能满足大部分运行需求，nvcc属于开发编译工具，不在 PyTorch 包里。如果你只装了 PyTorch，没有完整安装 CUDA 工具包，那么nvcc自然找不到。这不是环境坏了，而是功能缺失。当你需要安装某些需要编译 CUDA 扩展的第三方库时，会得到CUDA_HOME或nvcc找不到的错误。解决办法就是把对应版本的 CUDA 工具包装上，并配置好环境变量，确保nvcc -V能正常输出。
5.4 torchvision 和 torchaudio 版本对不上
这类问题通常是手动分别安装导致的。比如你之前装了 torch 2.0，后来单独装了一个新的 torchvision，它要求 torch>=2.1，然后 pip 会顺手把 torch 升级或降级，结果另一库又不兼容了。避免的要点是，这三大件最好在同一条安装命令里完成，或者在安装前看清楚版本映射关系。项目文档里如果只写了torchvision==0.16.0，那你基本能反推出它对应的是 torch 2.1 系列，而不要拿 torch 2.3 去硬凑。
5.5 安装下载速度慢或者校验失败
PyTorch 的 wheel 包体积很大，网络不稳定时特别容易下载到一半断掉。遇到这种情况，可以先清理 pip 缓存，再重试。如果公司或学校网络有限制，可以用官方挑出的镜像服务，但要注意镜像库不一定每个 CUDA 版本都同步完整，一旦发现镜像源里的文件版本和官方对不上，立刻切回官方 index-url。还有一个笨办法：用下载工具先把 wheel 文件下载下来，再pip install本地文件，文件名带不带 CUDA 后缀要看清。
6. 我的一点实操心得
这套环境我前前后后在好几台机器上装过，有 Windows 工作站，也有 Linux 服务器，总结下来最影响稳定性的其实是“克制”。不要一上来就把最新版全家桶装齐，也不要东装一个包西装一个包。先确定你的 GPU 型号能支持哪个算力等级，再确定想用的 PyTorch 版本，然后倒推需要哪个 CUDA 版本，最后一条命令三件套一起装，这样能少走很多弯路。
现实里还有一种情况，系统里已经存在了旧版 CUDA 或者多个 Python 解释器，导致安装时库被装到别的地方去了。我的习惯是，不管机器多乱，一定先建独立 conda 环境，在环境内操作。环境名直接叫torch-env就行，简单直白。所有验证步骤都用绝对路径或者激活环境后再执行，避免调用了系统默认的 Python。装完之后，写一个requirements.txt，把环境快照保存下来，这比记笔记管用多了。
最后再分享一个小技巧：每次安装完都要跑一遍我上面给的验证脚本，而且要看两样东西，torch.cuda.is_available()和torch.cuda.device_count()。前者为 True 只代表 torch 能访问 CUDA，后者能确认实际看到了几张卡。有时候你会发现 is_available 是 True，但 device_count 是 0，这种情况多半是显存被占满或者驱动层面没枚举到设备，后续训练同样起不来。环境搭建做到这一步，才算真正准备好了，接下来就能安心写模型了。
