做深度学习或者图像渲染的基本都逃不过这一关在Linux上装CUDA。这事儿官网看着很简单页面右上角点两下就能拿到安装命令但真到自己动手那真是一堆坑等着你。我第一次装的时候光一个CUDA .run gzip: stdin: invalid compressed># 用apt卸载旧驱动 sudo apt purge nvidia-* -y # 用runfile装过就用runfile自带卸载 sudo /usr/bin/nvidia-uninstall # 顺手清理一下可能残留的库 sudo apt autoremove -y卸载干净后重启一次再装新的这个习惯能救你很多次。尤其是你之前装的是NVIDIA显卡驱动后来换成AMD显卡或者反过来残留的内核模块会导致启动黑屏。别问我是怎么知道的。3.2 禁用Nouveau这一步不能省Nouveau是Linux内核自带的NVIDIA显卡开源驱动虽然功能弱但它会跟官方闭源驱动抢设备。不把它禁用掉装驱动时大概率报错或者装完驱动加载不了。Ubuntu和Debian系系统里建一个黑名单文件sudo nano /etc/modprobe.d/blacklist-nouveau.conf写上blacklist nouveau options nouveau modeset0然后更新内核引导并重启sudo update-initramfs -u sudo reboot重启后执行lsmod | grep nouveau没有输出就说明禁用成功了。CentOS/RHEL系用的是dracut流程类似但命令不同这里不再赘述。3.3 跑runfile时遇到gzip: stdin: invalid compressed># 官网页面会有md5值把它跟本地文件对比 md5sum cuda_12.4.0_550.54.14_linux.run第二下载到的其实是个HTML页面。这种情况多发生在公司代理、镜像站或者wget带错了参数的时候。runfile实际没下下来而是保存了一个错误页。用file命令一看就露馅file cuda_12.4.0_550.54.14_linux.run正常情况应该输出ELF 64-bit LSB executable或者类似的行如果你看到HTML document那恭喜你白下了。第三下载的是Windows版或者架构不对的包。Linux runfile和Windows安装包虽然都带cuda字样但字节结构完全不同。x86_64的机器别下ARM/aarch64版本。检查方法还是file命令加uname -m对照。处理完这三个原因这个报错基本能解决。顺带说一句那个报错前面还经常带着cuda .run字样看起来很吓人其实就是压缩层校验没通过问题不在系统在文件本身。3.4 安装并配置环境变量与验证确认文件没问题后开始安装。我的习惯是最小化安装sudo sh cuda_12.4.0_550.54.14_linux.run交互界面里注意第一步选择接受协议第二步有个很关键的选项如果你系统里已经用apt或其它方式装好了驱动这里一定要把Driver那一项的[X]给去掉让它只装Toolkit。如果你想顺带装驱动先确认系统里没有旧驱动否则容易冲突。选好组件后安装器会问安装路径默认是/usr/local/cuda-12.4这个路径很有用后面多版本切换就靠它。装完末尾提示要添加环境变量官方推荐写进~/.bashrcexport PATH/usr/local/cuda-12.4/bin${PATH::${PATH}} export LD_LIBRARY_PATH/usr/local/cuda-12.4/lib64${LD_LIBRARY_PATH::${LD_LIBRARY_PATH}}然后source ~/.bashrc验证三板斧nvcc --version nvidia-smi ls /usr/local/cuda-12.4nvcc能出版本号nvidia-smi能看到显卡和驱动信息第三个目录存在说明安装基本成功。4. 多版本CUDA共存与切换4.1 为什么需要多版本共存搞深度学习的人电脑里大概率同时有好几个项目有的项目只能在PyTorch 1.12 CUDA 11.3下跑有的项目又要求CUDA 12.1强迫你只保留一个版本那基本等于告别某些老项目。多版本共存不是装好几个驱动而是装多个CUDA Toolkit。注意驱动只需要一个且驱动版本要大于等于你所有Toolkit中要求的最高版本。Toolkit则可以并列装在/usr/local/cuda-11.x、/usr/local/cuda-12.x互不干扰。4.2 安装目录规划与软链接管理跑runfile安装多个版本时每装一个都有一步选择安装路径。默认路径是/usr/local/cuda-版本号比如cuda-12.4这个路径建议直接保留。NVIDIA安装器最后通常还会问你是否创建/usr/local/cuda软链接如果它帮你创建了这个软链接默认指向最新安装的版本。软链接/usr/local/cuda就是我们切换版本的关键。比如当前指向12.4ls -l /usr/local/cuda # /usr/local/cuda - /usr/local/cuda-12.4笔记里还没提到的是除了PATH变量LD_LIBRARY_PATH也要跟着变很多动态库找不到的问题就是变量没切干净。4.3 用切换脚本快速换版本手工每次改~/.bashrc里的路径太累写个小脚本放~/.cuda_switch.sh每次要切换的时候执行一下#!/bin/bash # 用法source ~/.cuda_switch.sh 12.4 CUDA_VERSION$1 export PATH/usr/local/cuda-${CUDA_VERSION}/bin:${PATH} export LD_LIBRARY_PATH/usr/local/cuda-${CUDA_VERSION}/lib64:${LD_LIBRARY_PATH} export CUDA_HOME/usr/local/cuda-${CUDA_VERSION}或者更简单直接改软链接本身sudo rm /usr/local/cuda sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda只要你的~/.bashrc里写的是软链接路径而不是写死的版本号改一次软链接就能全局切换。这个思路最稳推荐。4.4 新老版本迁移时的建议热搜词里有Cuda迁移这里提醒一个原则别删旧版本。把新版本装好、把项目在新环境跑通、把验证结果对比过确认无差异之后再考虑清理旧版本。清理时直接删目录就行不用卸载器因为Toolkit只是文件不涉及内核模块。迁移最常翻车的点在cuDNN。cuDNN是按CUDA主版本对应下载的比如8.x对应CUDA 12.x迁移后忘换cuDNN程序会在运行时直接报找不到libcudnn.so或者版本不匹配。装的时候记得把对应版本的libcudnn替换或链接到新的/usr/local/cuda/lib64里。5. 常见问题与排查技巧实录5.1 版本查看命令全家桶每次帮人排查环境第一件事就是让他把下面的输出贴给我nvidia-smi # 驱动版本、显卡、驱动支持的CUDA上限 nvcc --version # 当前默认Toolkit版本 ls /usr/local/cuda*/version.json # 看具体每个Toolkit的版本信息 cat /usr/local/cuda/version.json # CUDA 12.x以后用这个 python -c import torch; print(torch.version.cuda) # PyTorch自带的运行时CUDA版本 python -c import torch; print(torch.backends.cudnn.version()) # PyTorch里的cuDNN版本 conda list cudatoolkit # conda环境下的CUDA版本 conda list cudnn # conda环境下的cuDNN版本这一套命令打出去绝大多数版本不匹配问题都能暴露出来。特别提醒看到torch.version.cuda跟nvcc --version不一致是正常的因为PyTorch wheel自带运行库跟系统nvcc没有直接关系。5.2 WSL2里装CUDA的特殊之处很多人现在喜欢在Windows上用WSL2跑Linux环境这个方案我很喜欢但要注意一点WSL2里不要装NVIDIA驱动也不要装CUDA里的Driver组件。WSL2使用Windows侧的显卡驱动Linux端只需要装CUDA Toolkit即可。官方推荐的做法是sudo apt-key del 7fa2af80 wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update sudo apt install cuda-toolkit-12-4装完在WSL里敲nvidia-smi能正常显示显卡信息。如果发现WSL里nvidia-smi报错多半是Windows侧驱动太老或者没装不是Linux侧的问题。另外WSL2里跑CUDA程序一般直接走Windows驱动性能损耗很小放心用。5.3 conda环境下cudnn版本匹配用conda装cudatoolkit11.7之后配套的cuDNN最好也交给conda管conda install -c conda-forge cudnn8.4.1conda会检查cudatoolkit和cudnn的依赖关系一般不会出错。如果你非要手动下NVIDIA官网的cuDNN就必须去官网对应页面下载with CUDA 11.x的版本然后把解压出来的lib和include分别复制到conda环境的lib和include目录里。两种方式我都用过结论是让conda管最省事手动复制容易漏文件。5.4 其他让人崩溃的报错速查表报错/现象可能原因解决思路gzip: stdin: invalid compressed> Linux安装CUDA实战指南：从报错排查到多版本管理
做深度学习或者图像渲染的基本都逃不过这一关在Linux上装CUDA。这事儿官网看着很简单页面右上角点两下就能拿到安装命令但真到自己动手那真是一堆坑等着你。我第一次装的时候光一个CUDA .run gzip: stdin: invalid compressed># 用apt卸载旧驱动 sudo apt purge nvidia-* -y # 用runfile装过就用runfile自带卸载 sudo /usr/bin/nvidia-uninstall # 顺手清理一下可能残留的库 sudo apt autoremove -y卸载干净后重启一次再装新的这个习惯能救你很多次。尤其是你之前装的是NVIDIA显卡驱动后来换成AMD显卡或者反过来残留的内核模块会导致启动黑屏。别问我是怎么知道的。3.2 禁用Nouveau这一步不能省Nouveau是Linux内核自带的NVIDIA显卡开源驱动虽然功能弱但它会跟官方闭源驱动抢设备。不把它禁用掉装驱动时大概率报错或者装完驱动加载不了。Ubuntu和Debian系系统里建一个黑名单文件sudo nano /etc/modprobe.d/blacklist-nouveau.conf写上blacklist nouveau options nouveau modeset0然后更新内核引导并重启sudo update-initramfs -u sudo reboot重启后执行lsmod | grep nouveau没有输出就说明禁用成功了。CentOS/RHEL系用的是dracut流程类似但命令不同这里不再赘述。3.3 跑runfile时遇到gzip: stdin: invalid compressed># 官网页面会有md5值把它跟本地文件对比 md5sum cuda_12.4.0_550.54.14_linux.run第二下载到的其实是个HTML页面。这种情况多发生在公司代理、镜像站或者wget带错了参数的时候。runfile实际没下下来而是保存了一个错误页。用file命令一看就露馅file cuda_12.4.0_550.54.14_linux.run正常情况应该输出ELF 64-bit LSB executable或者类似的行如果你看到HTML document那恭喜你白下了。第三下载的是Windows版或者架构不对的包。Linux runfile和Windows安装包虽然都带cuda字样但字节结构完全不同。x86_64的机器别下ARM/aarch64版本。检查方法还是file命令加uname -m对照。处理完这三个原因这个报错基本能解决。顺带说一句那个报错前面还经常带着cuda .run字样看起来很吓人其实就是压缩层校验没通过问题不在系统在文件本身。3.4 安装并配置环境变量与验证确认文件没问题后开始安装。我的习惯是最小化安装sudo sh cuda_12.4.0_550.54.14_linux.run交互界面里注意第一步选择接受协议第二步有个很关键的选项如果你系统里已经用apt或其它方式装好了驱动这里一定要把Driver那一项的[X]给去掉让它只装Toolkit。如果你想顺带装驱动先确认系统里没有旧驱动否则容易冲突。选好组件后安装器会问安装路径默认是/usr/local/cuda-12.4这个路径很有用后面多版本切换就靠它。装完末尾提示要添加环境变量官方推荐写进~/.bashrcexport PATH/usr/local/cuda-12.4/bin${PATH::${PATH}} export LD_LIBRARY_PATH/usr/local/cuda-12.4/lib64${LD_LIBRARY_PATH::${LD_LIBRARY_PATH}}然后source ~/.bashrc验证三板斧nvcc --version nvidia-smi ls /usr/local/cuda-12.4nvcc能出版本号nvidia-smi能看到显卡和驱动信息第三个目录存在说明安装基本成功。4. 多版本CUDA共存与切换4.1 为什么需要多版本共存搞深度学习的人电脑里大概率同时有好几个项目有的项目只能在PyTorch 1.12 CUDA 11.3下跑有的项目又要求CUDA 12.1强迫你只保留一个版本那基本等于告别某些老项目。多版本共存不是装好几个驱动而是装多个CUDA Toolkit。注意驱动只需要一个且驱动版本要大于等于你所有Toolkit中要求的最高版本。Toolkit则可以并列装在/usr/local/cuda-11.x、/usr/local/cuda-12.x互不干扰。4.2 安装目录规划与软链接管理跑runfile安装多个版本时每装一个都有一步选择安装路径。默认路径是/usr/local/cuda-版本号比如cuda-12.4这个路径建议直接保留。NVIDIA安装器最后通常还会问你是否创建/usr/local/cuda软链接如果它帮你创建了这个软链接默认指向最新安装的版本。软链接/usr/local/cuda就是我们切换版本的关键。比如当前指向12.4ls -l /usr/local/cuda # /usr/local/cuda - /usr/local/cuda-12.4笔记里还没提到的是除了PATH变量LD_LIBRARY_PATH也要跟着变很多动态库找不到的问题就是变量没切干净。4.3 用切换脚本快速换版本手工每次改~/.bashrc里的路径太累写个小脚本放~/.cuda_switch.sh每次要切换的时候执行一下#!/bin/bash # 用法source ~/.cuda_switch.sh 12.4 CUDA_VERSION$1 export PATH/usr/local/cuda-${CUDA_VERSION}/bin:${PATH} export LD_LIBRARY_PATH/usr/local/cuda-${CUDA_VERSION}/lib64:${LD_LIBRARY_PATH} export CUDA_HOME/usr/local/cuda-${CUDA_VERSION}或者更简单直接改软链接本身sudo rm /usr/local/cuda sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda只要你的~/.bashrc里写的是软链接路径而不是写死的版本号改一次软链接就能全局切换。这个思路最稳推荐。4.4 新老版本迁移时的建议热搜词里有Cuda迁移这里提醒一个原则别删旧版本。把新版本装好、把项目在新环境跑通、把验证结果对比过确认无差异之后再考虑清理旧版本。清理时直接删目录就行不用卸载器因为Toolkit只是文件不涉及内核模块。迁移最常翻车的点在cuDNN。cuDNN是按CUDA主版本对应下载的比如8.x对应CUDA 12.x迁移后忘换cuDNN程序会在运行时直接报找不到libcudnn.so或者版本不匹配。装的时候记得把对应版本的libcudnn替换或链接到新的/usr/local/cuda/lib64里。5. 常见问题与排查技巧实录5.1 版本查看命令全家桶每次帮人排查环境第一件事就是让他把下面的输出贴给我nvidia-smi # 驱动版本、显卡、驱动支持的CUDA上限 nvcc --version # 当前默认Toolkit版本 ls /usr/local/cuda*/version.json # 看具体每个Toolkit的版本信息 cat /usr/local/cuda/version.json # CUDA 12.x以后用这个 python -c import torch; print(torch.version.cuda) # PyTorch自带的运行时CUDA版本 python -c import torch; print(torch.backends.cudnn.version()) # PyTorch里的cuDNN版本 conda list cudatoolkit # conda环境下的CUDA版本 conda list cudnn # conda环境下的cuDNN版本这一套命令打出去绝大多数版本不匹配问题都能暴露出来。特别提醒看到torch.version.cuda跟nvcc --version不一致是正常的因为PyTorch wheel自带运行库跟系统nvcc没有直接关系。5.2 WSL2里装CUDA的特殊之处很多人现在喜欢在Windows上用WSL2跑Linux环境这个方案我很喜欢但要注意一点WSL2里不要装NVIDIA驱动也不要装CUDA里的Driver组件。WSL2使用Windows侧的显卡驱动Linux端只需要装CUDA Toolkit即可。官方推荐的做法是sudo apt-key del 7fa2af80 wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update sudo apt install cuda-toolkit-12-4装完在WSL里敲nvidia-smi能正常显示显卡信息。如果发现WSL里nvidia-smi报错多半是Windows侧驱动太老或者没装不是Linux侧的问题。另外WSL2里跑CUDA程序一般直接走Windows驱动性能损耗很小放心用。5.3 conda环境下cudnn版本匹配用conda装cudatoolkit11.7之后配套的cuDNN最好也交给conda管conda install -c conda-forge cudnn8.4.1conda会检查cudatoolkit和cudnn的依赖关系一般不会出错。如果你非要手动下NVIDIA官网的cuDNN就必须去官网对应页面下载with CUDA 11.x的版本然后把解压出来的lib和include分别复制到conda环境的lib和include目录里。两种方式我都用过结论是让conda管最省事手动复制容易漏文件。5.4 其他让人崩溃的报错速查表报错/现象可能原因解决思路gzip: stdin: invalid compressed>