PyTorch CUDA不可用？从False到True的完整排查指南

1. 从一次深夜调试说起那个让人抓狂的False如果你写过PyTorch代码大概率在某个时刻敲下过这行命令import torch print(torch.cuda.is_available())然后满怀期待地等着屏幕上跳出那个令人安心的True结果等来的却是一个冷冰冰的False。更让人崩溃的是你明明记得昨天还是True今天重启了一下机器就变了或者你刚换了一台新机器显卡看起来一切正常驱动也装了但PyTorch就是不认。这个问题的排查难度在于它不像语法错误那样会给你一个明确的报错信息。False只是一个结果它背后可能对应着七八种完全不同的原因。你如果不知道排查的顺序很容易陷入重装驱动→重装CUDA→重装PyTorch→还是False→再重装的死循环。我自己在这个问题上前后踩过至少五次坑每一次的原因都不一样。有一次是驱动版本和CUDA运行时不匹配有一次是装成了CPU版本的PyTorch还有一次最离谱——系统里有两套Python环境我在终端里激活的和Jupyter Notebook里用的根本不是同一个。这篇文章就是把这些年积累的排查经验完整地梳理一遍。我会按照从最表层到最底层的顺序把每一个可能导致False的原因拆开来讲清楚包括怎么判断是不是这个问题、怎么修复、以及修复之后怎么验证。不管你是刚接触深度学习的新手还是已经跑过几个项目的老手这篇内容都值得收藏因为这个问题你迟早还会再遇到。2. 先搞清楚is_available()到底在检查什么2.1 这个函数的判断逻辑不是有没有显卡很多人对torch.cuda.is_available()有一个误解以为它是在检测这台机器上有没有NVIDIA显卡。实际上不是的。这个函数的判断逻辑要复杂得多它本质上是在回答一个问题PyTorch当前这个进程能不能正常使用CUDA进行计算具体来说它内部会依次检查以下几个条件PyTorch这个包本身是不是CUDA版本而不是CPU-only版本系统里能不能加载到CUDA运行时库比如libcudart.so或cudart64_*.dll显卡驱动是否正常加载驱动版本是否满足CUDA运行时要求的最低版本能不能成功创建一个CUDA上下文这一步会实际调用驱动接口只要上面任何一环出了问题返回值就是False。所以你不能简单地把它等同于有没有显卡。2.2 为什么它不告诉你具体哪里出了问题这是PyTorch设计上一个让人又爱又恨的地方。is_available()只返回一个布尔值不提供任何诊断信息。它的定位就是一个快速检查的开关不是诊断工具。但PyTorch其实提供了更详细的诊断手段。你可以用torch.version.cuda查看PyTorch编译时链接的CUDA版本用torch.backends.cudnn.version()查看cuDNN版本通过nvidia-smi查看驱动支持的CUDA版本。这几个信息组合起来基本就能定位问题所在。记住一个原则is_available()返回False的时候不要急着重装任何东西。先收集信息再动手。2.3 一个容易被忽略的事实编译版本和运行时版本是两回事PyTorch在发布的时候会针对不同的CUDA版本编译出不同的wheel包。比如torch-2.x.xcu118表示这个包是用CUDA 11.8编译的torch-2.x.xcu121表示用CUDA 12.1编译的。你通过pip安装的时候默认可能会装到CPU版本也可能装到某个CUDA版本取决于你的pip源和安装命令。而系统里实际安装的显卡驱动支持的最高CUDA版本是另一个概念。驱动版本决定了你最高能用哪个版本的CUDA运行时而PyTorch编译时链接的CUDA版本决定了它需要哪个版本的运行时。这两个版本如果不匹配就会出现各种问题。最常见的情况是PyTorch编译时用的是CUDA 12.1但系统驱动太老只支持到CUDA 11.8这时候is_available()就会返回False。3. 排查第一步确认你装的是不是CPU版本的PyTorch3.1 这是最常见也最容易修复的原因我敢说初次遇到False的人里面至少有三分之一是因为装成了CPU版本的PyTorch。尤其是用pip install torch这种不带任何后缀的命令安装的时候pip默认会从PyPI拉取CPU版本的包。怎么确认运行下面这行代码import torch print(torch.__version__)如果输出类似2.1.0cpu这样的字符串那基本可以确定你装的是CPU版本。注意那个cpu后缀这是最明确的标志。如果输出的是2.1.0后面没有任何后缀那可能是CUDA版本也可能是CPU版本需要进一步确认。你可以用print(torch.version.cuda)如果输出是None那就是CPU版本无疑了。如果输出类似11.8或12.1说明是CUDA版本。3.2 正确的安装命令长什么样确认是CPU版本之后卸载重装就行。但安装命令有讲究不能随便写。以CUDA 11.8为例正确的命令是pip uninstall torch torchvision torchaudio -y pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118注意--index-url这个参数它指定了从PyTorch官方的CUDA专用源下载而不是从默认的PyPI。如果你不加这个参数pip还是会给你装CPU版本。对于CUDA 12.1把cu118换成cu121即可。安装完成后再运行一次torch.version.cuda应该能看到对应的版本号。3.3 一个真实的踩坑案例我之前帮一个同学排查这个问题他的情况特别典型。他在终端里用pip install torch装了PyTorch然后在Jupyter Notebook里测试一直是False。我让他运行torch.__version__输出是2.0.1cpu确认是CPU版本。然后他卸载重装用了正确的CUDA源终端里测试通过了True。但Jupyter Notebook里还是False。这就引出了下一个大坑——多环境问题。4. 多Python环境下的薛定谔的CUDA4.1 为什么终端里是TrueNotebook里是False这个问题的根源在于你的终端和你的Jupyter Notebook可能使用的是两个完全不同的Python解释器。在终端里你运行python命令调用的可能是/usr/bin/python3或者某个conda环境里的Python。而Jupyter Notebook启动的时候它绑定的是某个特定的kernel这个kernel背后是另一个Python解释器。如果你在终端里给A环境装了CUDA版本的PyTorch但Jupyter用的是B环境的kernel那B环境里可能还是CPU版本或者根本没装PyTorch。4.2 怎么确认当前用的是哪个Python在终端里which python python -c import sys; print(sys.executable)在Jupyter Notebook里import sys print(sys.executable)对比这两个输出。如果路径不一样那就是环境不一致的问题。4.3 统一环境的几种做法最直接的做法是在Jupyter里安装一个指向正确环境的kernel# 假设你的正确环境叫myenv conda activate myenv pip install ipykernel python -m ipykernel install --user --namemyenv --display-namePython (myenv)然后在Jupyter的Kernel菜单里选择Python (myenv)。这样Notebook和终端就用的是同一个环境了。另一种做法是直接在Jupyter的cell里用!pip install来安装这样装到的就是当前kernel对应的环境。但我不太推荐这种做法因为!pip有时候会指向错误的pip反而不如显式指定环境来得可靠。经验之谈但凡是终端里正常、Notebook里不正常或者反过来Notebook里正常、终端里不正常的情况九成以上都是环境不一致导致的。先查sys.executable能省下大量重装的时间。5. 驱动、CUDA运行时、PyTorch三者的版本匹配问题5.1 用nvidia-smi读出关键信息在终端里运行nvidia-smi这个命令会输出一个表格右上角有一个CUDA Version: XX.X的标识。注意这个数字不是你系统里安装的CUDA版本而是你的显卡驱动最高支持的CUDA运行时版本。举个例子如果显示CUDA Version: 12.2意味着你的驱动可以支持最高12.2版本的CUDA运行时。你可以安装11.8的CUDA运行时也可以安装12.1的都没问题。但如果你安装12.3的CUDA运行时就会因为驱动太老而无法使用。5.2 版本匹配的规则这里有一个简化的匹配规则表驱动显示的CUDA Version可以使用的PyTorch CUDA版本典型安装命令后缀11.811.8及以下cu11812.112.1及以下cu12112.212.2及以下cu12112.2通常兼容12.412.4及以下cu124关键原则是PyTorch编译时用的CUDA版本不能高于驱动支持的最高版本。如果你不确定最保险的做法是选择一个比驱动支持版本低一到两个小版本的PyTorch。比如驱动显示12.4你装cu121的PyTorch基本不会有问题。5.3 驱动太老怎么办如果nvidia-smi显示的CUDA Version太低比如只有11.4而你想用cu118的PyTorch那就需要更新显卡驱动。在Linux上可以通过包管理器更新也可以从NVIDIA官网下载runfile手动安装。手动安装的时候注意要先把旧驱动卸干净否则容易出现版本冲突。在Windows上直接下载最新的驱动安装包运行安装程序选择自定义安装并勾选执行清洁安装这样会先卸载旧驱动再装新的。更新完驱动之后重启系统再运行nvidia-smi确认版本已经上去了。5.4 一个隐蔽的坑CUDA运行时被LD_LIBRARY_PATH干扰在Linux系统上有时候系统里装了多个版本的CUDA运行时而LD_LIBRARY_PATH环境变量指向了一个错误的版本。这种情况下即使PyTorch本身没问题加载的时候也会加载到错误的库导致is_available()返回False。排查方法echo $LD_LIBRARY_PATH看看输出的路径里有没有包含CUDA相关的目录。如果有确认一下这些目录下的CUDA版本是否和PyTorch匹配。如果不匹配可以临时清空这个变量测试LD_LIBRARY_PATH python -c import torch; print(torch.cuda.is_available())如果这样能返回True那就说明是LD_LIBRARY_PATH的问题需要调整环境变量配置。6. 那些不常见但确实存在的奇葩原因6.1 显卡被其他进程独占在某些情况下显卡可能被其他进程独占了。比如你之前跑了一个训练任务没有正常退出显存没有释放或者在某些配置下显卡被设置成了独占模式。用nvidia-smi可以看到当前显卡上有哪些进程在运行。如果显存占用很高但你没有在跑任何任务那可能就是有僵尸进程。找到对应的PID用kill -9结束掉。6.2 Docker容器里没有透传显卡如果你是在Docker容器里运行PyTorch那需要确保容器启动的时候做了显卡透传。否则容器里根本看不到显卡is_available()自然是False。启动容器的时候需要加上--gpus all参数需要先安装nvidia-container-toolkit。进入容器后运行nvidia-smi如果能正常输出说明透传成功了。6.3 WSL2环境下的特殊配置在WSL2里使用显卡需要Windows端的驱动支持WSL。如果Windows端的驱动太老或者没有安装WSL专用的驱动组件WSL里就看不到显卡。确认方法是在WSL里运行nvidia-smi如果提示命令找不到或者报错那就是WSL的显卡支持没配好。需要去NVIDIA官网下载支持WSL的Windows驱动安装后重启WSL。6.4 硬件本身的问题虽然概率很低但确实遇到过显卡硬件故障导致is_available()返回False的情况。这种时候nvidia-smi可能也会报错或者干脆没有任何输出。如果排除了所有软件层面的原因可以尝试把显卡插到另一台机器上测试或者用其他工具如CUDA Samples里的deviceQuery来确认显卡是否正常工作。7. 一套完整的排查流程7.1 从外到内的检查顺序我把上面所有的排查点整理成一个有序的流程你按照这个顺序走一遍基本能覆盖95%以上的情况运行nvidia-smi确认显卡能被系统识别驱动正常加载运行python -c import torch; print(torch.__version__)确认PyTorch版本运行python -c import torch; print(torch.version.cuda)确认是否为CPU版本如果是CPU版本用正确的CUDA源重装确认终端和IDE/Notebook使用的是同一个Python环境检查驱动支持的CUDA版本是否满足PyTorch的要求检查LD_LIBRARY_PATH是否指向了错误的CUDA库如果是容器环境确认显卡透传配置如果是WSL2确认Windows端驱动支持7.2 一个万能的诊断脚本我把常用的诊断信息写成了一个脚本遇到问题的时候直接跑一遍所有关键信息一目了然import torch import sys import os print( * 50) print(fPython executable: {sys.executable}) print(fPython version: {sys.version}) print(fPyTorch version: {torch.__version__}) print(fCUDA available: {torch.cuda.is_available()}) print(fPyTorch CUDA version: {torch.version.cuda}) print(fcuDNN version: {torch.backends.cudnn.version()}) print(fLD_LIBRARY_PATH: {os.environ.get(LD_LIBRARY_PATH, Not set)}) print(fCUDA_HOME: {os.environ.get(CUDA_HOME, Not set)}) if torch.cuda.is_available(): print(fDevice count: {torch.cuda.device_count()}) print(fDevice name: {torch.cuda.get_device_name(0)}) print(fCapability: {torch.cuda.get_device_capability(0)}) print( * 50)把这个脚本保存成check_cuda.py在终端里运行python check_cuda.py把输出结果保存下来。不管你是自己排查还是去社区提问这份信息都是最有价值的。7.3 排查时容易犯的几个错误第一个错误是一上来就重装。重装驱动、重装CUDA、重装PyTorch一套下来少说半小时而且很可能根本没解决问题因为方向就错了。第二个错误是只看一个信息就下结论。比如看到nvidia-smi正常就认为驱动没问题但实际上驱动正常不代表版本匹配。第三个错误是忽略环境问题。尤其是在Windows上很多人同时装了多个Python版本加上conda环境情况非常复杂。不确认清楚当前用的是哪个Python后面的排查都是白费功夫。8. 修复之后的验证与长期维护建议8.1 验证不只看is_available()is_available()返回True只是第一步。真正要确认CUDA能正常工作还需要做一次实际的张量运算import torch # 基础检查 assert torch.cuda.is_available(), CUDA not available # 实际运算测试 x torch.randn(1000, 1000).cuda() y torch.randn(1000, 1000).cuda() z torch.mm(x, y) print(fMatrix multiplication result shape: {z.shape}) print(fDevice: {z.device}) # 检查显存分配 print(fAllocated: {torch.cuda.memory_allocated() / 1024**2:.2f} MB) print(fCached: {torch.cuda.memory_reserved() / 1024**2:.2f} MB)这段代码会实际在显卡上分配内存并做一次矩阵乘法。如果这一步能跑通说明CUDA环境是真正可用的而不只是is_available()返回了True。8.2 用conda环境锁定版本为了避免以后再次出现版本不匹配的问题我强烈建议用conda来管理环境并且在创建环境的时候就锁定版本conda create -n pytorch_env python3.10 conda activate pytorch_env conda install pytorch torchvision torchaudio pytorch-cuda11.8 -c pytorch -c nvidia用conda安装的好处是它会自动处理CUDA运行时和PyTorch之间的依赖关系减少手动匹配版本的工作量。8.3 记录环境配置每次配好一个能正常工作的环境之后把关键信息记录下来pip freeze requirements.txt nvidia-smi gpu_info.txt这样下次换机器或者重装系统的时候直接照着记录来配不用再从头排查一遍。8.4 关于版本升级的策略我的建议是如果一个环境能正常工作不要轻易升级。尤其是显卡驱动和CUDA运行时升级带来的收益往往不值得冒的风险。除非你需要用到某个新版本才支持的特性否则保持现状是最稳妥的选择。如果确实需要升级先在另一个环境里测试通过之后再切换不要直接在主环境上操作。9. 写在最后的一些个人体会排查torch.cuda.is_available()返回False这个问题最核心的能力不是技术知识而是排查的思路和顺序。你知道先看什么、再看什么就能在几分钟内定位问题。如果顺序反了可能折腾半天还在原地打转。我自己的习惯是遇到这个问题第一件事永远是跑那个诊断脚本把sys.executable、torch.__version__、torch.version.cuda、nvidia-smi这四个信息拿到手。这四个信息一出来问题基本就定位了八成。另外说一个心态上的事情。这个问题有时候确实会让人很烦躁尤其是赶项目的时候突然发现显卡用不了了。但越是这种时候越要冷静按照流程一步步来。我见过太多人因为着急把本来只是环境变量的问题搞成了重装系统反而浪费了更多时间。还有一个实用的小技巧如果你用的是远程服务器而且有多张显卡记得检查一下CUDA_VISIBLE_DEVICES这个环境变量。有时候这个变量被设置成了空字符串或者一个不存在的设备编号也会导致is_available()返回False。这个坑很隐蔽因为nvidia-smi看起来一切正常但PyTorch就是看不到显卡。echo $CUDA_VISIBLE_DEVICES如果输出是空或者不是你期望的值用export CUDA_VISIBLE_DEVICES0或者对应的编号来修正。最后如果你按照这篇文章的流程走了一遍还是没解决那大概率是硬件层面的问题了。这时候可以尝试用CUDA官方提供的deviceQuery工具来做一个最终的确认。如果deviceQuery也报错那就不是PyTorch的问题了需要从显卡硬件或者驱动层面去排查。