Ubuntu 20.04 安装 CUDA 12 与 cuDNN：深度学习环境配置完整指南

Ubuntu 20.04 安装 CUDA 12 与 cuDNN：深度学习环境配置完整指南

发布时间：2026/8/13 3:27:09
Ubuntu 20.04 安装 CUDA 12 与 cuDNN：深度学习环境配置完整指南 1. 项目概述与核心价值最近在帮几个刚入行的朋友和实验室的师弟配置深度学习环境发现大家普遍卡在CUDA和cuDNN的安装上尤其是用Ubuntu系统的新手。网上的教程要么太老要么步骤跳跃太大一个依赖没装对或者版本没选对后面就是一连串的“未找到命令”或者“版本不兼容”。所以我决定把在Ubuntu 20.04 LTS上通过官方deb包安装CUDA 12和对应cuDNN的完整流程以及最重要的验证方法重新梳理一遍。这个流程最大的优点就是“干净”和“可控”所有组件都通过系统包管理器管理升级、卸载都方便不容易把系统搞乱。即便是对Linux命令行还不太熟悉的“宝宝”们只要跟着步骤一步步来也能顺利搭建起自己的AI开发环境。2. 环境准备与前置检查在开始安装任何软件之前做好准备工作是避免后续踩坑的关键。对于CUDA和cuDNN的安装这一步尤为重要它决定了你的系统是否具备安装条件以及应该选择哪个版本的安装包。2.1 系统与硬件确认首先我们需要确认两件事你的Ubuntu系统版本和你的NVIDIA显卡型号。打开终端输入以下命令查看系统信息lsb_release -a你应该能看到类似Description: Ubuntu 20.04.6 LTS的输出确认是20.04版本。接着检查你的显卡是否支持CUDA。虽然大部分NVIDIA独立显卡都支持但核显或非常老的显卡可能不行。使用lspci命令过滤查看lspci | grep -i nvidia如果能看到你的显卡型号比如NVIDIA Corporation GA106 [GeForce RTX 3060]那就没问题。一个更直接的方法是访问NVIDIA官网的CUDA支持页面查看你的显卡是否在列表内。2.2 驱动安装与清理CUDA Toolkit本身包含了驱动程序但为了避免冲突我强烈建议先使用系统源或NVIDIA官方PPA安装一个合适的驱动或者至少确保没有陈旧的驱动残留。如果你之前用runfile方式装过驱动或CUDA最好先清理一下。首先检查当前已安装的NVIDIA驱动版本nvidia-smi如果这个命令能正常执行并输出显卡信息说明驱动已经存在。记下右上角显示的CUDA Version例如12.4这表示当前驱动最高支持的CUDA运行时版本。注意这个CUDA Version是驱动支持的CUDA运行时最高版本不是你将要安装的CUDA Toolkit版本但你的CUDA Toolkit版本不能超过它。如果你想使用Ubuntu仓库的驱动可以这样安装sudo apt update sudo ubuntu-drivers devices # 查看推荐驱动 sudo apt install nvidia-driver-535 # 安装一个推荐版本例如535安装后需要重启。如果你想追求最新驱动可以添加NVIDIA官方PPA但稳定性可能稍逊于系统仓库版本。关键注意事项如果你之前通过任何非deb方式比如.run文件安装过CUDA或驱动在安装deb包之前最好运行官方的清理脚本或手动卸载否则极易导致冲突。NVIDIA提供了卸载脚本通常位于/usr/local/cuda/bin下名为cuda-uninstaller。在安装新的deb包前一个干净的环境至关重要。2.3 安装必要依赖项为了保证deb包安装过程顺畅我们需要先安装一些基础工具和依赖。这些工具主要用于密钥管理、包验证和传输。sudo apt update sudo apt install -y build-essential software-properties-common sudo apt install -y gcc make perl dkms linux-headers-$(uname -r)build-essential包含了编译所需的基本工具gcc, g, make等dkms是动态内核模块支持对于内核更新后自动重建设备驱动非常重要。linux-headers-$(uname -r)则是安装当前运行内核的头文件这是编译内核模块比如NVIDIA驱动模块所必需的。3. CUDA Toolkit 12的deb方式安装这是整个流程的核心部分。我们将采用NVIDIA官方提供的网络deb仓库进行安装。这种方式的好处是未来可以通过apt upgrade来更新CUDA并且所有文件都遵循Linux文件系统标准管理起来非常清晰。3.1 添加NVIDIA官方CUDA仓库首先我们需要获取并添加NVIDIA的包仓库密钥和地址。这一步确保了我们将从官方源下载安装包保证了安全性和兼容性。下载并添加密钥NVIDIA使用公钥来签名他们的软件包我们需要将这个公钥添加到系统的可信密钥列表中。wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb这个.deb文件包含了仓库密钥和源信息。安装后它会自动在/etc/apt/trusted.gpg.d/和/etc/apt/sources.list.d/下放置相应文件。更新软件包列表添加新仓库后必须更新本地的包索引这样apt才能知道这个新源里有哪些可用的软件包。sudo apt update3.2 选择并安装CUDA包更新后我们就可以搜索和安装CUDA了。这里有一个非常重要的选择安装cuda还是cuda-toolkit-12-x在NVIDIA的deb仓库中cuda是一个元包它本身不包含太多内容而是依赖于当前最新的CUDA Toolkit完整包例如cuda-toolkit-12-5。安装元包的好处是当你下次执行sudo apt upgrade时如果仓库里有新版本的CUDA比如12.6它会自动升级到新版本。但这可能带来不确定性因为新版本可能引入不兼容的变更。对于生产环境或希望环境长期稳定的用户我推荐安装特定版本的Toolkit包。我们先查看可用的版本apt search cuda-toolkit-12- | grep ^cuda-toolkit假设我们想安装CUDA 12.5则执行sudo apt install -y cuda-toolkit-12-5如果你想使用最新的12.x版本并接受自动更新可以安装元包sudo apt install -y cuda安装过程详解执行安装命令后apt会解析出这个包所需的所有依赖包括特定版本的NVIDIA驱动、CUDA运行时库、编译器、工具等。它会提示你将安装一系列软件包如cuda-drivers-550, cuda-runtime-12-5, cuda-compiler-12-5, cuda-libraries-12-5等并显示需要下载的数据量和磁盘空间占用。确认后安装过程会自动进行这可能需要一些时间取决于你的网速。3.3 配置环境变量安装完成后CUDA的可执行文件和库文件被安装到了/usr/local/cuda-12.5版本号可能不同目录下。为了让系统在任何位置都能识别到CUDA的命令和动态链接库我们需要将相关路径添加到环境变量中。最常用的方法是修改用户家目录下的~/.bashrc文件如果你使用zsh则是~/.zshrc。打开配置文件nano ~/.bashrc在文件末尾添加以下几行export PATH/usr/local/cuda-12.5/bin${PATH::${PATH}} export LD_LIBRARY_PATH/usr/local/cuda-12.5/lib64${LD_LIBRARY_PATH::${LD_LIBRARY_PATH}}参数解释PATH添加CUDA的bin目录这样你可以在终端直接运行nvccCUDA编译器、nvidia-smi等命令。LD_LIBRARY_PATH添加CUDA的lib64目录这样运行时系统才能找到CUDA的动态链接库如libcudart.so。保存文件在nano中按CtrlO回车然后CtrlX退出并让配置立即生效source ~/.bashrc实操心得有些教程会建议你创建一个软链接/usr/local/cuda指向具体的版本目录如cuda-12.5。这样做的好处是当你切换CUDA版本时只需要更改这个软链接的目标而无需修改环境变量。deb安装方式通常会自动创建这个软链接。你可以用ls -l /usr/local/cuda检查。如果存在且指向正确那么你的环境变量可以直接设置为/usr/local/cuda这样会更灵活。4. cuDNN的deb方式安装cuDNN是NVIDIA提供的深度神经网络加速库它实现了高度优化的标准例程如前向/反向卷积、池化、归一化等。大多数深度学习框架如TensorFlow, PyTorch在GPU上运行时都依赖于cuDNN。它的版本必须与已安装的CUDA版本严格匹配。4.1 下载正确的cuDNN deb包与CUDA不同cuDNN的deb包需要从NVIDIA开发者网站手动下载。你需要注册一个免费的NVIDIA开发者账号。访问 NVIDIA cuDNN下载页面 。登录后在筛选条件中选择CUDA Version选择你刚刚安装的CUDA版本例如CUDA 12.x。Operating System选择Linux。Architecture选择x86_64。Distribution选择Ubuntu。Version选择20.04。Installer Type这里我们选择Deb (Local)即本地deb包。你会看到几个可选的deb包。通常有三个libcudnn8运行时库。libcudnn8-dev开发文件头文件和静态库编译深度学习框架时需要。libcudnn8-samples示例代码。 对于深度学习环境前两个是必须的。请下载它们例如libcudnn8_8.x.x.x-1cuda12.x_amd64.deblibcudnn8-dev_8.x.x.x-1cuda12.x_amd64.deb版本匹配黄金法则cuDNN的主版本号如8和次版本号必须与你的深度学习框架所要求的版本兼容。例如TensorFlow 2.15.0 要求 cuDNN 8.9。请务必查阅你将要使用的框架的官方安装文档确认其支持的cuDNN版本然后下载对应的包。下载页面上的“CUDA Version”是它兼容的CUDA版本而包名里的cuda12.x是它设计运行于的CUDA环境两者必须一致。4.2 安装cuDNN deb包下载完成后在终端中进入存放deb文件的目录按顺序安装它们。先安装运行时库再安装开发包。sudo dpkg -i libcudnn8_8.x.x.x-1cuda12.x_amd64.deb sudo dpkg -i libcudnn8-dev_8.x.x.x-1cuda12.x_amd64.debdpkg -i是Debian/Ubuntu系统安装本地deb包的命令。安装过程会将cuDNN的库文件复制到系统目录如/usr/lib/x86_64-linux-gnu/和/usr/include/并将头文件链接到CUDA的include目录下。常见问题处理如果安装过程中报告依赖错误例如dpkg: dependency problems prevent configuration of...可以运行sudo apt --fix-broken install或sudo apt install -f来自动安装缺失的依赖并完成配置。这是因为deb包可能依赖一些其他系统库而dpkg本身不解决依赖关系apt可以。4.3 验证cuDNN安装安装完成后如何确认cuDNN已正确安装并与CUDA链接呢最直接的方法是检查头文件和库文件。验证头文件cuDNN的头文件应该被链接到了CUDA的include目录。cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2或者如果上述文件不存在可以尝试cat /usr/include/cudnn_version.h | grep CUDNN_MAJOR -A 2这条命令会输出cuDNN的主版本、次版本和补丁版本号例如#define CUDNN_MAJOR 8 #define CUDNN_MINOR 9 #define CUDNN_PATCHLEVEL 6这表示你安装的是 cuDNN 8.9.6。验证库文件检查动态链接库是否存在且可被识别。ldconfig -p | grep cudnn这条命令会列出系统中所有名为libcudnn的库缓存。你应该能看到类似libcudnn.so.8 (libc6,x86-64)的输出。5. 完整环境验证与测试安装完所有组件后我们必须进行系统性验证确保从驱动到CUDA运行时再到cuDNN整个链条都是通畅的。这是将环境投入实际使用前的最后一道也是最重要的一道检查。5.1 驱动与CUDA运行时验证我们之前用过的nvidia-smi是驱动层面的工具。要验证CUDA运行时我们需要使用CUDA Toolkit自带的工具。基础命令验证nvidia-smi确认命令能运行并检查右上角的“CUDA Version”它应大于或等于你安装的CUDA Toolkit版本如12.5。nvcc --version这是CUDA编译器驱动NVCC的版本。它输出的版本号应该与你安装的CUDA Toolkit版本一致如release 12.5。如果提示“命令未找到”请检查你的环境变量PATH是否设置正确。编译并运行CUDA样例CUDA Toolkit自带了许多示例代码位于/usr/local/cuda-12.5/samples或/usr/local/cuda/samples。我们可以编译一个最简单的例子来测试。# 切换到示例目录 cd /usr/local/cuda/samples/1_Utilities/deviceQuery # 编译示例这需要一些时间 sudo make # 运行编译好的程序 ./deviceQuery如果一切正常这个程序会输出你GPU的详细信息并在最后显示Result PASS。这表明CUDA驱动和运行时通信正常GPU可以被CUDA程序访问。5.2 cuDNN功能验证验证cuDNN不仅需要检查文件是否存在最好能运行一个实际调用cuDNN API的程序。我们可以使用之前安装的cuDNN示例包如果安装了libcudnn8-samples或者自己写一个简单的测试程序。使用官方示例如果已安装# 解压示例代码假设示例包已安装 cp -r /usr/src/cudnn_samples_v8/ $HOME cd $HOME/cudnn_samples_v8/mnistCUDNN # 编译示例 make clean make # 运行测试 ./mnistCUDNN如果输出Test passed!则证明cuDNN安装成功且功能正常。编写简易Python测试脚本更常用对于深度学习用户通过Python接口测试更直接。首先确保你安装了cuda-python或深度学习框架。pip install nvidia-cudnn-cu128.9.6 # 安装对应版本的cuDNN Python包PyTorch等框架会自带然后在一个Python交互环境中尝试导入import torch print(torch.cuda.is_available()) # 应返回 True print(torch.backends.cudnn.version()) # 应输出你安装的cuDNN版本号如 8906对应8.9.6如果这两步都成功那么你的PyTorch CUDA cuDNN环境就完全就绪了。对于TensorFlow可以类似地使用tf.config.list_physical_devices(GPU)和检查版本来验证。5.3 环境隔离与多版本管理建议在实际工作中你可能需要为不同的项目维护不同的CUDA环境。虽然deb安装方式将CUDA安装在系统路径但我们可以通过环境变量和虚拟环境来隔离。使用环境变量切换如果你安装了多个CUDA版本如11.8和12.5可以创建不同的shell脚本在脚本中设置不同的PATH和LD_LIBRARY_PATH指向不同的CUDA目录。运行项目前先source对应的脚本。结合Conda虚拟环境这是更推荐的做法。在Conda虚拟环境中安装深度学习框架如PyTorch, TensorFlow时使用conda install命令。Conda会自动为该环境安装匹配的CUDA和cuDNN库这些库被安装在虚拟环境内部与系统隔离。这样你可以轻松拥有多个互不干扰的深度学习环境。系统通过deb安装的CUDA更多是作为一个“后备”或“编译器”存在。6. 安装后常见问题深度排查即使按照步骤操作也可能会遇到一些问题。这里我总结几个最常见的问题及其排查思路这往往是教程里不会细说的“坑”。6.1 NVIDIA-SMI 可以运行但 NVCC 报错“未找到命令”问题现象nvidia-smi正常显示但nvcc --version提示命令未找到。根本原因环境变量PATH没有包含CUDA的bin目录或者.bashrc修改后没有source。排查步骤检查CUDA安装路径是否存在ls -l /usr/local/cuda*。确认/usr/local/cuda这个软链接是否存在并指向正确的版本目录如cuda-12.5。检查当前shell的PATHecho $PATH查看输出中是否包含/usr/local/cuda/bin或/usr/local/cuda-12.5/bin。如果PATH中没有请确认~/.bashrc中的设置是否正确并执行source ~/.bashrc。如果使用的是zsh请确保修改的是~/.zshrc并source它。极端情况下可能是CUDA Toolkit没有安装完整。可以尝试重新安装sudo apt install --reinstall cuda-toolkit-12-5。6.2 运行程序时报错“libcudnn.so.8: cannot open shared object file”问题现象在导入PyTorch或运行自己编译的程序时提示找不到cuDNN的某个库文件。根本原因动态链接器找不到cuDNN库。LD_LIBRARY_PATH环境变量未设置或设置错误或者cuDNN库未正确安装/链接。排查步骤首先确认库文件是否存在ls -l /usr/lib/x86_64-linux-gnu/libcudnn*。你应该能看到libcudnn.so.8 - libcudnn.so.8.x.x这样的软链接和实体文件。检查LD_LIBRARY_PATHecho $LD_LIBRARY_PATH确认它包含了CUDA的lib64目录如/usr/local/cuda/lib64。cuDNN的库通常会被链接到系统库目录但CUDA的库需要这个路径。更新动态链接器缓存运行sudo ldconfig。这个命令会重建库的缓存有时安装新库后需要手动执行。如果上述步骤都正确问题可能出在程序的运行时链接上。你可以尝试直接指定库路径运行程序LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH ./your_program。如果能运行则证明是环境变量问题。6.3 系统内核更新后NVIDIA驱动失效问题现象执行了sudo apt upgrade升级了系统内核后重启电脑无法进入图形界面或者nvidia-smi无法运行。根本原因内核升级后之前为旧内核编译的NVIDIA内核模块由dkms管理与新内核不兼容。虽然我们通过deb方式安装驱动通常配置了DKMS但有时自动构建会失败。解决方案重启系统在GRUB引导界面选择高级选项然后选择之前的内核版本启动。进入系统后再处理驱动问题。为当前新内核重新编译NVIDIA内核模块sudo dkms install -m nvidia -v $(modinfo nvidia | grep version | awk {print $2})或者更直接的方法是重新安装驱动包sudo apt install --reinstall nvidia-driver-535 # 替换成你的驱动版本重启系统选择新的内核启动检查是否恢复正常。预防措施对于重要的生产机器可以考虑暂时禁止自动内核更新或者在更新内核后预留一个恢复用的旧内核启动项。6.4 深度学习框架无法检测到GPU问题现象在Python中torch.cuda.is_available()返回False。排查思路这是一个综合性问题需要按顺序排查。驱动层面nvidia-smi是否正常工作如果不工作回到问题6.3。CUDA运行时层面运行/usr/local/cuda/samples/1_Utilities/deviceQuery是否通过如果不通过说明CUDA运行时安装或配置有问题。框架层面PyTorch检查安装的PyTorch版本是否支持你的CUDA版本。访问 PyTorch官网 查看版本匹配矩阵。使用conda install pytorch torchvision torchaudio cudatoolkit12.1 -c pytorch这样的命令时cudatoolkit12.1必须与你系统的CUDA版本兼容可以略低不能更高。TensorFlowTensorFlow 2.x之后GPU支持直接打包在tensorflow包中但其对CUDA/cuDNN的版本要求非常严格。必须严格按照 TensorFlow官网 列出的版本对应表来安装。使用pip install tensorflow安装的是支持CUDA的版本但其依赖的CUDA动态库需要你系统预先安装好。虚拟环境隔离如果你在Conda虚拟环境中请确认你是在该环境中运行的Python和框架。有时在终端激活了环境但在Jupyter Notebook或IDE中可能没有。整个安装和验证过程最需要耐心和细致的就是版本匹配。记住一个简单的链条深度学习框架版本 - 所需CUDA版本 - 所需cuDNN版本 - 所需NVIDIA驱动版本。任何一个环节版本不匹配都可能导致失败。养成在安装前先查阅框架官方安装文档的习惯能节省大量排查时间。