WSL Ubuntu 24.04 GPU 加速环境完整安装指南

WSL Ubuntu 24.04 GPU 加速环境完整安装指南环境版本总览软件版本说明Ubuntu24.04.4 LTSWSL2Python3.12.3系统自带NVIDIA 驱动595.79Windows 主机驱动nvidia-utils590.48.01WSL 内 nvidia-smi 工具CUDA Toolkit13.2.78 12.9.86双版本共存可选cuDNN9.21.0.82 (JIT/FULL)CUDA 13.x 配套可选PyTorch2.13.0.dev20260417cu132CUDA 13.2 nightlyTensorFlow2.21.0CUDA 12.x 内置运行时架构说明PyTorch 和 TensorFlow 通过 pip 安装的nvidia-*Python 包自带 CUDA 运行时库不需要系统 CUDA 即可使用 GPU。系统 CUDA 仅用于编译自定义 CUDA 代码和使用开发工具。一、安装前准备1. 安装 Windows NVIDIA GPU 驱动官方下载页面: https://www.nvidia.com/drivers说明WSL2 的 GPU 加速依赖 Windows 主机的 NVIDIA 驱动不需要在 WSL 内安装任何 GPU 驱动。现代 NVIDIA Windows 驱动版本 470已内置 WSL2 GPU 支持安装后 WSL2 会自动识别并使用 GPU。步骤访问 NVIDIA 驱动下载页面选择适合你显卡型号的驱动版本下载并在 Windows 中安装安装完成后重启 Windows2. 设置系统时区sudotimedatectl set-timezone Asia/Shanghai验证时区设置timedatectl3. 系统环境升级sudoaptupdatesudoapt-ydist-upgrade4. 安装基础工具包sudoapt-yinstallpython3 python3-pip python3-venv nvidia-utils-590 build-essential说明nvidia-utils-590提供nvidia-smi命令用于查看 GPU 状态。build-essential提供 gcc/g 等 C/C 编译工具。Ubuntu 仓库中 nvidia-utils 最新版本为 590向下兼容更新驱动版本如 595。5. 验证 GPU 驱动识别nvidia-smi6. pip 国内镜像源配置清华大学源推荐pip3 configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simple阿里云源备选pip3 configsetglobal.index-url https://mirrors.aliyun.com/pypi/simple验证配置pip3 config list7. Python 环境说明PEP 668Ubuntu 24.04 使用 PEP 668 保护机制不要在系统层面使用 pip 安装包。正确做法创建虚拟环境在虚拟环境内使用 pip。二、选择安装路径根据你的需求选择安装路径路径适用场景安装内容最小安装仅使用 PyTorch/TensorFlow 训练和推理框架 自带 CUDA 运行时完整安装需要编译 CUDA 代码、使用开发工具系统 CUDA cuDNN 框架核心原理现代 PyTorch 和 TensorFlow 通过 pip 安装的nvidia-*Python 包自带 CUDA 运行时库不需要系统 CUDA 即可使用 GPU。三、最小安装仅框架适用场景仅使用 PyTorch/TensorFlow 进行深度学习不需要编译 CUDA 代码。1. PyTorch 项目安装CUDA 13.2创建项目目录和虚拟环境mkdir-p~/pytorch-projectcd~/pytorch-project python3-mvenv .venvsource.venv/bin/activate pipinstall--upgradepip setuptools wheel安装 PyTorch GPU 版本pipinstall--pretorch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132说明--pre参数安装预发布版本cu132表示 CUDA 13.2 编译版本。安装时会自动下载并安装约 29 个nvidia-*CUDA 运行时包无需额外命令。这些包包含 CUDA 13.2 运行时库nvidia-cuda-runtime-cu13、nvidia-cudnn-cu13等框架会自动加载。验证 PyTorch GPUpython3-c import torch print(fPyTorch版本: {torch.__version__}) print(fCUDA可用: {torch.cuda.is_available()}) print(fCUDA版本: {torch.version.cuda}) print(fcuDNN版本: {torch.backends.cudnn.version()}) print(fGPU设备: {torch.cuda.get_device_name(0)}) x torch.randn(100, 100).to(cuda) y torch.randn(100, 100).to(cuda) z torch.matmul(x, y) print(fGPU矩阵乘法: {z.shape} OK) 2. TensorFlow 项目安装CUDA 12.x创建项目目录和虚拟环境mkdir-p~/tensorflow-projectcd~/tensorflow-project python3-mvenv .venvsource.venv/bin/activate pipinstall--upgradepip setuptools wheel安装 TensorFlow GPU 版本pipinstalltensorflow[and-cuda]说明tensorflow[and-cuda]会自动安装约 12 个nvidia-*CUDA 12.x 运行时包无需额外命令。这些包包含 CUDA 12.x 运行时库nvidia-cuda-runtime-cu12、nvidia-cudnn-cu12等框架会自动加载。不需要系统 CUDA 环境变量。验证 TensorFlow GPUpython3-c import tensorflow as tf print(fTensorFlow版本: {tf.__version__}) gpus tf.config.list_physical_devices(GPU) print(fGPU设备: {len(gpus)} 个) for gpu in gpus: print(f - {gpu}) if gpus: with tf.device(/GPU:0): a tf.constant([[1.0, 2.0], [3.0, 4.0]]) b tf.constant([[5.0, 6.0], [7.0, 8.0]]) c tf.matmul(a, b) print(fGPU矩阵乘法结果:) print(c.numpy()) 四、完整安装系统 CUDA cuDNN 框架适用场景需要编译自定义 CUDA 代码、使用 CUDA 开发工具Nsight 等、开发 C/C 深度学习框架。1. 安装 C/C 编译环境sudoapt-yinstallbuild-essential说明build-essential包含 gcc、g、make 等基础编译工具是编译 CUDA/C 代码的必备环境。2. 安装 CUDA Toolkit 双版本13.2 12.9配置 NVIDIA 软件源mkdir-p~/cudawgethttps://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb-P~/cudasudodpkg-i~/cuda/cuda-keyring_1.1-1_all.debsudoapt-getupdate安装 CUDA 13.2PyTorch 编译用sudoapt-get-yinstallcuda-toolkit-13-2安装 CUDA 12.9TensorFlow 编译用sudoapt-get-yinstallcuda-toolkit-12-9安装完成后系统会有两个 CUDA 版本/usr/local/cuda-13.2/- CUDA 13.2.78/usr/local/cuda-12.9/- CUDA 12.9.86配置 CUDA 版本切换工具创建~/cuda-switch.shcat~/cuda-switch.shEOF #!/bin/bash # CUDA 版本切换脚本 # 用法: source ~/cuda-switch.sh [12.9|13.2] switch_cuda() { local version$1 case $version in 12.9|12) export CUDA_HOME/usr/local/cuda-12.9 export PATH/usr/local/cuda-12.9/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.9/lib64:$LD_LIBRARY_PATH echo 已切换到 CUDA 12.9 ;; 13.2|13) export CUDA_HOME/usr/local/cuda-13.2 export PATH/usr/local/cuda-13.2/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-13.2/lib64:$LD_LIBRARY_PATH echo 已切换到 CUDA 13.2 ;; *) echo 用法: source ~/cuda-switch.sh [12.9|13|13.2] return 1 ;; esac nvcc --version | grep release } switch_cuda $1 EOFchmodx ~/cuda-switch.sh使用方法source~/cuda-switch.sh12.9# 切换到 CUDA 12.9source~/cuda-switch.sh13.2# 切换到 CUDA 13.2设置默认 CUDA 版本可选如果需要使用nvcc命令建议设置默认版本echoexport PATH/usr/local/cuda-13.2/bin:$PATH~/.bashrcechoexport LD_LIBRARY_PATH/usr/local/cuda-13.2/lib64:$LD_LIBRARY_PATH~/.bashrcsource~/.bashrc重要不要在~/.bashrc中设置 CUDA 环境变量给 PyTorch/TensorFlow 使用。现代框架通过 pip 安装的nvidia-*Python 包自带 CUDA 运行时不依赖系统环境变量。系统 CUDA 仅用于nvcc编译和开发工具。验证安装/usr/local/cuda-13.2/bin/nvcc--version/usr/local/cuda-12.9/bin/nvcc--version3. 安装 cuDNN 9.21.0JIT vs FULL 版本说明JIT(Just-In-Time)仅包含运行时编译引擎体积较小。PyTorch 和 TensorFlow 在运行时动态编译优化推荐选择。FULL包含所有预编译引擎 JIT 引擎体积较大。适用于需要预编译引擎的 C/C 项目。本指南使用 JIT 版本如需 FULL 版本将cudnn-jit替换为cudnn。下载并安装 cuDNNmkdir-p~/cudnnwgethttps://developer.download.nvidia.com/compute/cudnn/9.21.0/local_installers/cudnn-local-repo-ubuntu2404-9.21.0_1.0-1_amd64.deb-P~/cudnnsudodpkg-i~/cudnn/cudnn-local-repo-ubuntu2404-9.21.0_1.0-1_amd64.debsudocp/var/cudnn-local-repo-ubuntu2404-9.21.0/cudnn-local-*-keyring.gpg /usr/share/keyrings/sudoapt-getupdatesudoapt-get-yinstallcudnn-jit复制库文件和头文件到 CUDA 13.2 目录sudocp-v/usr/lib/x86_64-linux-gnu/libcudnn* /usr/local/cuda-13.2/targets/x86_64-linux/lib/sudocp-v/usr/include/x86_64-linux-gnu/cudnn*.h /usr/local/cuda-13.2/targets/x86_64-linux/include/修复所有符号链接cd/usr/local/cuda-13.2/targets/x86_64-linux/lib/# libcudnnsudorm-flibcudnn.so libcudnn.so.9sudoln-slibcudnn.so.9.21.0 libcudnn.so.9sudoln-slibcudnn.so.9 libcudnn.so# libcudnn_engines_runtime_compiledsudorm-flibcudnn_engines_runtime_compiled.so libcudnn_engines_runtime_compiled.so.9sudoln-slibcudnn_engines_runtime_compiled.so.9.21.0 libcudnn_engines_runtime_compiled.so.9sudoln-slibcudnn_engines_runtime_compiled.so.9 libcudnn_engines_runtime_compiled.so# libcudnn_graphsudorm-flibcudnn_graph.so libcudnn_graph.so.9sudoln-slibcudnn_graph.so.9.21.0 libcudnn_graph.so.9sudoln-slibcudnn_graph.so.9 libcudnn_graph.so# libcudnn_engines_tensor_irsudorm-flibcudnn_engines_tensor_ir.so libcudnn_engines_tensor_ir.so.9sudoln-slibcudnn_engines_tensor_ir.so.9.21.0 libcudnn_engines_tensor_ir.so.9sudoln-slibcudnn_engines_tensor_ir.so.9 libcudnn_engines_tensor_ir.so更新动态链接库缓存sudoldconfig验证安装ldconfig-p|greplibcudnn4. 安装框架同最小安装完成系统 CUDA 和 cuDNN 安装后按照第三章的步骤安装 PyTorch 和 TensorFlow 即可。五、C/C 测试程序目的验证 CUDA 和 cuDNN 的 C/C 开发环境是否正常工作为开发 C/C 深度学习框架提供基础验证。1. C 语言测试程序程序说明cuda_cudnn_test.cu是一个全面的 C 语言测试程序用于验证 CUDA 和 cuDNN 的核心功能。测试流程分为 10 个阶段阶段测试内容目的1CUDA 设备查询确认 GPU 硬件和驱动正确识别2CUDA 内存管理验证 GPU 内存分配和数据传输功能3CUDA 内核执行验证 GPU 并行计算能力4cuDNN 初始化验证 cuDNN 库能正常加载和初始化5cuDNN 张量操作验证 cuDNN 张量描述符创建和查询功能6cuDNN 卷积操作验证 cuDNN 卷积配置和算法查询功能7cuDNN 池化操作验证 cuDNN 池化配置功能8cuDNN 激活函数验证 cuDNN 激活函数配置功能9cuDNN 批量归一化验证 cuDNN 批量归一化配置功能10cuDNN 前向推理完整流程验证完整的 cuDNN 卷积前向推理流程编译方法# 切换到 CUDA 13.2 环境source~/cuda-switch.sh13.2# 编译 C 测试程序nvcc-ocuda_cudnn_test cuda_cudnn_test.cu-lcudnn运行方法./cuda_cudnn_test2. C 语言测试程序程序说明cuda_cudnn_test_cpp.cu是一个使用现代 C 特性的测试程序与 C 版本相比增加了以下特性RAII 资源管理自动管理 cuDNN 句柄、描述符、GPU 内存等资源避免内存泄漏C 异常处理定义CudaException和CudnnException异常类提供详细错误信息std::vector 替代原始数组自动管理内存分配和释放提供安全的边界检查std::unique_ptr 管理 cuDNN 对象使用自定义删除器管理 cuDNN 对象生命周期模板函数简化类型处理DeviceMemoryT模板类支持任意数据类型Lambda 表达式简化激活函数测试代码避免重复代码测试流程与 C 版本相同分为 10 个阶段但增加了额外的 C 特性验证。编译方法# 切换到 CUDA 13.2 环境source~/cuda-switch.sh13.2# 编译 C 测试程序nvcc-ocuda_cudnn_test_cpp cuda_cudnn_test_cpp.cu-lcudnn-stdc17运行方法./cuda_cudnn_test_cpp六、PyTorch/TensorFlow 测试程序目的验证 PyTorch 和 TensorFlow 框架的 GPU 加速和 cuDNN 集成是否正常工作。1. PyTorch 测试程序程序说明verify_pytorch_cudnn.py是一个全面的 PyTorch GPU 验证脚本测试流程分为 4 个阶段阶段测试内容目的1环境信息检查确认 PyTorch 版本、CUDA 可用性、GPU 设备信息2基础张量操作验证 GPU 上的基本矩阵运算3cuDNN 功能验证测试卷积、池化、批量归一化等深度学习核心操作4性能基准测试测量 100 次卷积操作的耗时评估 GPU 性能运行方法cd~/pytorch-projectsource.venv/bin/activate python verify_pytorch_cudnn.py2. TensorFlow 测试程序程序说明verify_tensorflow_gpu.py是一个全面的 TensorFlow GPU 验证脚本测试流程分为 3 个阶段阶段测试内容目的1环境信息检查确认 TensorFlow 版本、GPU 设备信息2GPU 计算测试在 GPU 上执行矩阵乘法验证计算正确性3内存与性能测试检查 GPU 内存使用情况执行简单性能测试运行方法cd~/tensorflow-projectsource.venv/bin/activate python verify_tensorflow_gpu.py七、常见问题与解决方案1. CUDA 相关Q:nvidia-smi显示 CUDA 版本与安装的 CUDA Toolkit 版本不一致A:nvidia-smi显示的是驱动支持的最高 CUDA 版本不是实际安装的 CUDA Toolkit 版本。实际版本使用nvcc --version查看。Q: 编译 CUDA 代码时找不到cuda.h或cudnn.hA: 确保已正确设置 CUDA 环境变量source~/cuda-switch.sh13.2或者在编译时指定路径nvcc -I/usr/local/cuda-13.2/include -L/usr/local/cuda-13.2/lib64-otesttest.cuQ: 运行时找不到 cuDNN 库libcudnn.so not foundA: 确保已更新动态链接库缓存sudoldconfig并检查库文件是否存在ldconfig-p|greplibcudnn2. PyTorch 相关Q: PyTorch 显示CUDA available: FalseA: 检查以下几点nvidia-smi是否正常显示 GPU是否安装了 GPU 版本的 PyTorchpip show torch查看虚拟环境是否正确激活Q: PyTorch 批量归一化报告CUDNN_STATUS_SUBLIBRARY_VERSION_MISMATCHA: 这是 PyTorch 自带 cuDNN 子库与系统 cuDNN 版本不兼容导致的。不影响其他功能可以忽略或等待 PyTorch 更新。3. TensorFlow 相关Q: TensorFlow 显示No GPU devices foundA: 检查以下几点nvidia-smi是否正常显示 GPU是否安装了tensorflow[and-cuda]而非tensorflow虚拟环境是否正确激活4. C/C 编译相关Q:nvcc编译时报错undefined reference to cudnnCreateA: 确保链接了 cuDNN 库nvcc-otesttest.cu-lcudnnQ: C 代码编译时报错undefined reference to std::...A: 确保使用了正确的 C 标准nvcc-otesttest.cu-lcudnn-stdc17八、附录1. 常用命令速查命令说明nvidia-smi查看 GPU 状态nvcc --version查看 CUDA 编译器版本source ~/cuda-switch.sh 13.2切换到 CUDA 13.2source ~/cuda-switch.sh 12.9切换到 CUDA 12.9ldconfig -pgrep libcudnnpython3 -m venv .venv创建 Python 虚拟环境source .venv/bin/activate激活虚拟环境deactivate退出虚拟环境2. 目录结构~ ├── cuda/ # CUDA 安装包目录 ├── cudnn/ # cuDNN 安装包目录 ├── cuda-switch.sh # CUDA 版本切换脚本 ├── cuda_cudnn_test.cu # C 语言 CUDA/cuDNN 测试程序 ├── cuda_cudnn_test_cpp.cu # C 语言 CUDA/cuDNN 测试程序 ├── verify_pytorch_cudnn.py # PyTorch GPU 验证脚本 ├── verify_tensorflow_gpu.py # TensorFlow GPU 验证脚本 ├── pytorch-project/ # PyTorch 项目目录 │ └── .venv/ # Python 虚拟环境 └── tensorflow-project/ # TensorFlow 项目目录 └── .venv/ # Python 虚拟环境3. 关键路径路径说明/usr/local/cuda-13.2/CUDA 13.2 安装目录/usr/local/cuda-12.9/CUDA 12.9 安装目录/usr/local/cudaCUDA 符号链接指向当前默认版本/usr/lib/x86_64-linux-gnu/libcudnn*系统 cuDNN 库文件/usr/include/x86_64-linux-gnu/cudnn*.h系统 cuDNN 头文件4. 参考链接NVIDIA 驱动下载CUDA Toolkit 文档cuDNN 文档PyTorch 安装指南TensorFlow 安装指南文档版本: v2.2更新日期: 2026-04-18包含验证脚本:verify_pytorch_cudnn.py,verify_tensorflow_gpu.py,cuda_cudnn_test.cu,cuda_cudnn_test_cpp.cu