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

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

环境版本总览

软件	版本	说明
Ubuntu	24.04.4 LTS	WSL2
Python	3.12.3	系统自带
NVIDIA 驱动	595.79	Windows 主机驱动
nvidia-utils	590.48.01	WSL 内 nvidia-smi 工具
CUDA Toolkit	13.2.78 + 12.9.86	双版本共存（可选）
cuDNN	9.21.0.82 (JIT/FULL)	CUDA 13.x 配套（可选）
PyTorch	2.13.0.dev20260417+cu132	CUDA 13.2 nightly
TensorFlow	2.21.0	CUDA 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。

步骤：

1. 访问 NVIDIA 驱动下载页面
2. 选择适合你显卡型号的驱动版本
3. 下载并在 Windows 中安装
4. 安装完成后重启 Windows

2. 设置系统时区

sudo timedatectl set-timezone Asia/Shanghai

验证时区设置：

timedatectl

3. 系统环境升级

sudo apt update && sudo apt -y dist-upgrade

4. 安装基础工具包

sudo apt -y install python3 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-smi

6. pip 国内镜像源配置

清华大学源（推荐）：

pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

阿里云源（备选）：

pip3 config set global.index-url https://mirrors.aliyun.com/pypi/simple

验证配置：

pip3 config list

7. Python 环境说明（PEP 668）

Ubuntu 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-project && cd ~/pytorch-project
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel

安装 PyTorch GPU 版本

pip install --pre torch 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 GPU

python3 -c "
import torch
print(f'PyTorch版本: {torch.__version__}')
print(f'CUDA可用: {torch.cuda.is_available()}')
print(f'CUDA版本: {torch.version.cuda}')
print(f'cuDNN版本: {torch.backends.cudnn.version()}')
print(f'GPU设备: {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(f'GPU矩阵乘法: {z.shape} OK')
"

2. TensorFlow 项目安装（CUDA 12.x）

创建项目目录和虚拟环境

mkdir -p ~/tensorflow-project && cd ~/tensorflow-project
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel

安装 TensorFlow GPU 版本

pip install tensorflow[and-cuda]

说明：

• tensorflow[and-cuda] 会自动安装约 12 个 nvidia-* CUDA 12.x 运行时包，无需额外命令。
• 这些包包含 CUDA 12.x 运行时库（nvidia-cuda-runtime-cu12、nvidia-cudnn-cu12 等），框架会自动加载。
• 不需要系统 CUDA 环境变量。

验证 TensorFlow GPU

python3 -c "
import tensorflow as tf
print(f'TensorFlow版本: {tf.__version__}')
gpus = tf.config.list_physical_devices('GPU')
print(f'GPU设备: {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(f'GPU矩阵乘法结果:')
        print(c.numpy())
"

---

四、完整安装（系统 CUDA + cuDNN + 框架）

适用场景：需要编译自定义 CUDA 代码、使用 CUDA 开发工具（Nsight 等）、开发 C/C++ 深度学习框架。

1. 安装 C/C++ 编译环境

sudo apt -y install build-essential

说明 ：build-essential 包含 gcc、g++、make 等基础编译工具，是编译 CUDA/C++ 代码的必备环境。

2. 安装 CUDA Toolkit 双版本（13.2 + 12.9）

配置 NVIDIA 软件源

mkdir -p ~/cuda
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb -P ~/cuda
sudo dpkg -i ~/cuda/cuda-keyring_1.1-1_all.deb
sudo apt-get update

安装 CUDA 13.2（PyTorch 编译用）

sudo apt-get -y install cuda-toolkit-13-2

安装 CUDA 12.9（TensorFlow 编译用）

sudo apt-get -y install cuda-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.sh：

cat > ~/cuda-switch.sh << 'EOF'
#!/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"
EOF
chmod +x ~/cuda-switch.sh

使用方法：

source ~/cuda-switch.sh 12.9   # 切换到 CUDA 12.9
source ~/cuda-switch.sh 13.2   # 切换到 CUDA 13.2

设置默认 CUDA 版本（可选）

如果需要使用 nvcc 命令，建议设置默认版本：

echo 'export PATH=/usr/local/cuda-13.2/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-13.2/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.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 --version

3. 安装 cuDNN 9.21.0

JIT vs FULL 版本说明：

• JIT (Just-In-Time)：仅包含运行时编译引擎，体积较小。PyTorch 和 TensorFlow 在运行时动态编译优化，推荐选择。
• FULL：包含所有预编译引擎 + JIT 引擎，体积较大。适用于需要预编译引擎的 C/C++ 项目。

本指南使用 JIT 版本，如需 FULL 版本将 cudnn-jit 替换为 cudnn。

下载并安装 cuDNN

mkdir -p ~/cudnn
wget https://developer.download.nvidia.com/compute/cudnn/9.21.0/local_installers/cudnn-local-repo-ubuntu2404-9.21.0_1.0-1_amd64.deb -P ~/cudnn
sudo dpkg -i ~/cudnn/cudnn-local-repo-ubuntu2404-9.21.0_1.0-1_amd64.deb
sudo cp /var/cudnn-local-repo-ubuntu2404-9.21.0/cudnn-local-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cudnn-jit

复制库文件和头文件到 CUDA 13.2 目录

sudo cp -v /usr/lib/x86_64-linux-gnu/libcudnn* /usr/local/cuda-13.2/targets/x86_64-linux/lib/
sudo cp -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/

# libcudnn
sudo rm -f libcudnn.so libcudnn.so.9
sudo ln -s libcudnn.so.9.21.0 libcudnn.so.9
sudo ln -s libcudnn.so.9 libcudnn.so

# libcudnn_engines_runtime_compiled
sudo rm -f libcudnn_engines_runtime_compiled.so libcudnn_engines_runtime_compiled.so.9
sudo ln -s libcudnn_engines_runtime_compiled.so.9.21.0 libcudnn_engines_runtime_compiled.so.9
sudo ln -s libcudnn_engines_runtime_compiled.so.9 libcudnn_engines_runtime_compiled.so

# libcudnn_graph
sudo rm -f libcudnn_graph.so libcudnn_graph.so.9
sudo ln -s libcudnn_graph.so.9.21.0 libcudnn_graph.so.9
sudo ln -s libcudnn_graph.so.9 libcudnn_graph.so

# libcudnn_engines_tensor_ir
sudo rm -f libcudnn_engines_tensor_ir.so libcudnn_engines_tensor_ir.so.9
sudo ln -s libcudnn_engines_tensor_ir.so.9.21.0 libcudnn_engines_tensor_ir.so.9
sudo ln -s libcudnn_engines_tensor_ir.so.9 libcudnn_engines_tensor_ir.so

更新动态链接库缓存

sudo ldconfig

验证安装

ldconfig -p | grep libcudnn

4. 安装框架（同最小安装）

完成系统 CUDA 和 cuDNN 安装后，按照第三章的步骤安装 PyTorch 和 TensorFlow 即可。

---

五、C/C++ 测试程序

目的：验证 CUDA 和 cuDNN 的 C/C++ 开发环境是否正常工作，为开发 C/C++ 深度学习框架提供基础验证。

1. C 语言测试程序

程序说明

cuda_cudnn_test.cu 是一个全面的 C 语言测试程序，用于验证 CUDA 和 cuDNN 的核心功能。测试流程分为 10 个阶段：

阶段	测试内容	目的
1	CUDA 设备查询	确认 GPU 硬件和驱动正确识别
2	CUDA 内存管理	验证 GPU 内存分配和数据传输功能
3	CUDA 内核执行	验证 GPU 并行计算能力
4	cuDNN 初始化	验证 cuDNN 库能正常加载和初始化
5	cuDNN 张量操作	验证 cuDNN 张量描述符创建和查询功能
6	cuDNN 卷积操作	验证 cuDNN 卷积配置和算法查询功能
7	cuDNN 池化操作	验证 cuDNN 池化配置功能
8	cuDNN 激活函数	验证 cuDNN 激活函数配置功能
9	cuDNN 批量归一化	验证 cuDNN 批量归一化配置功能
10	cuDNN 前向推理（完整流程）	验证完整的 cuDNN 卷积前向推理流程

编译方法

# 切换到 CUDA 13.2 环境
source ~/cuda-switch.sh 13.2

# 编译 C 测试程序
nvcc -o cuda_cudnn_test cuda_cudnn_test.cu -lcudnn

运行方法

./cuda_cudnn_test

2. C++ 语言测试程序

程序说明

cuda_cudnn_test_cpp.cu 是一个使用现代 C++ 特性的测试程序，与 C 版本相比增加了以下特性：

• RAII 资源管理：自动管理 cuDNN 句柄、描述符、GPU 内存等资源，避免内存泄漏
• C++ 异常处理 ：定义 CudaException 和 CudnnException 异常类，提供详细错误信息
• std::vector 替代原始数组：自动管理内存分配和释放，提供安全的边界检查
• std::unique_ptr 管理 cuDNN 对象：使用自定义删除器管理 cuDNN 对象生命周期
• 模板函数简化类型处理 ：DeviceMemory<T> 模板类支持任意数据类型
• Lambda 表达式：简化激活函数测试代码，避免重复代码

测试流程与 C 版本相同，分为 10 个阶段，但增加了额外的 C++ 特性验证。

编译方法

# 切换到 CUDA 13.2 环境
source ~/cuda-switch.sh 13.2

# 编译 C++ 测试程序
nvcc -o cuda_cudnn_test_cpp cuda_cudnn_test_cpp.cu -lcudnn -std=c++17

运行方法

./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 上的基本矩阵运算
3	cuDNN 功能验证	测试卷积、池化、批量归一化等深度学习核心操作
4	性能基准测试	测量 100 次卷积操作的耗时，评估 GPU 性能

运行方法

cd ~/pytorch-project && source .venv/bin/activate
python verify_pytorch_cudnn.py

2. TensorFlow 测试程序

程序说明

verify_tensorflow_gpu.py 是一个全面的 TensorFlow GPU 验证脚本，测试流程分为 3 个阶段：

阶段	测试内容	目的
1	环境信息检查	确认 TensorFlow 版本、GPU 设备信息
2	GPU 计算测试	在 GPU 上执行矩阵乘法，验证计算正确性
3	内存与性能测试	检查 GPU 内存使用情况，执行简单性能测试

运行方法

cd ~/tensorflow-project && source .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.h？

A: 确保已正确设置 CUDA 环境变量：

source ~/cuda-switch.sh 13.2

或者在编译时指定路径：

nvcc -I/usr/local/cuda-13.2/include -L/usr/local/cuda-13.2/lib64 -o test test.cu

Q: 运行时找不到 cuDNN 库（libcudnn.so not found）？

A: 确保已更新动态链接库缓存：

sudo ldconfig

并检查库文件是否存在：

ldconfig -p | grep libcudnn

2. PyTorch 相关

Q: PyTorch 显示 CUDA available: False？

A: 检查以下几点：

1. nvidia-smi 是否正常显示 GPU
2. 是否安装了 GPU 版本的 PyTorch（pip show torch 查看）
3. 虚拟环境是否正确激活

Q: PyTorch 批量归一化报告 CUDNN_STATUS_SUBLIBRARY_VERSION_MISMATCH？

A: 这是 PyTorch 自带 cuDNN 子库与系统 cuDNN 版本不兼容导致的。不影响其他功能，可以忽略或等待 PyTorch 更新。

3. TensorFlow 相关

Q: TensorFlow 显示 No GPU devices found？

A: 检查以下几点：

1. nvidia-smi 是否正常显示 GPU
2. 是否安装了 tensorflow[and-cuda] 而非 tensorflow
3. 虚拟环境是否正确激活

4. C/C++ 编译相关

Q: nvcc 编译时报错 undefined reference to cudnnCreate？

A: 确保链接了 cuDNN 库：

nvcc -o test test.cu -lcudnn

Q: C++ 代码编译时报错 undefined reference to std::...？

A: 确保使用了正确的 C++ 标准：

nvcc -o test test.cu -lcudnn -std=c++17

---

八、附录

1. 常用命令速查

命令	说明
nvidia-smi	查看 GPU 状态
nvcc --version	查看 CUDA 编译器版本
source ~/cuda-switch.sh 13.2	切换到 CUDA 13.2
source ~/cuda-switch.sh 12.9	切换到 CUDA 12.9
`ldconfig -p	grep libcudnn`
python3 -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/cuda	CUDA 符号链接（指向当前默认版本）
/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