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

李昊哲-小课

553人浏览 · 2026-04-18 20:14:24

李昊哲-小课 · 2026-04-18 20:14:24 发布

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。

步骤：

访问 NVIDIA 驱动下载页面
选择适合你显卡型号的驱动版本
下载并在 Windows 中安装
安装完成后重启 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: 检查以下几点：

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

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

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

3. TensorFlow 相关

Q: TensorFlow 显示 `No GPU devices found`？

A: 检查以下几点：

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

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. 参考链接

文档版本: v2.2
更新日期: 2026-04-18
包含验证脚本: verify_pytorch_cudnn.py, verify_tensorflow_gpu.py, cuda_cudnn_test.cu, cuda_cudnn_test_cpp.cu

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

程序员学 AI（八）：AI Agent 到底是什么？从回答问题到完成任务

AI Agent技术社区

22道AI Agent 工程师必会的面试题，别啥都不会就出去找工作

AI Agent技术社区

基于AI agent的智能图书馆

AI Agent技术社区

所有评论(0)

查看更多评论

李昊哲-小课

@qq_24330181

已为社区贡献19条内容

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

李昊哲-小课

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

环境版本总览

一、安装前准备

1. 安装 Windows NVIDIA GPU 驱动

2. 设置系统时区

3. 系统环境升级

4. 安装基础工具包

5. 验证 GPU 驱动识别

6. pip 国内镜像源配置

7. Python 环境说明（PEP 668）

二、选择安装路径

三、最小安装（仅框架）

1. PyTorch 项目安装（CUDA 13.2）

创建项目目录和虚拟环境

安装 PyTorch GPU 版本

验证 PyTorch GPU

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

创建项目目录和虚拟环境

安装 TensorFlow GPU 版本

验证 TensorFlow GPU

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

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

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

配置 NVIDIA 软件源

安装 CUDA 13.2（PyTorch 编译用）

安装 CUDA 12.9（TensorFlow 编译用）

配置 CUDA 版本切换工具

设置默认 CUDA 版本（可选）

验证安装

3. 安装 cuDNN 9.21.0

下载并安装 cuDNN

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

修复所有符号链接

更新动态链接库缓存

验证安装

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

五、C/C++ 测试程序

1. C 语言测试程序

程序说明

编译方法

运行方法

2. C++ 语言测试程序

程序说明

编译方法

运行方法

六、PyTorch/TensorFlow 测试程序

1. PyTorch 测试程序

程序说明

运行方法

2. TensorFlow 测试程序

程序说明

运行方法

七、常见问题与解决方案

1. CUDA 相关

Q: nvidia-smi 显示 CUDA 版本与安装的 CUDA Toolkit 版本不一致？

Q: 编译 CUDA 代码时找不到 cuda.h 或 cudnn.h？

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

2. PyTorch 相关

Q: PyTorch 显示 CUDA available: False？

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

3. TensorFlow 相关

Q: TensorFlow 显示 No GPU devices found？

4. C/C++ 编译相关

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

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

八、附录

1. 常用命令速查

2. 目录结构

3. 关键路径

4. 参考链接

所有评论(0)

温馨提示：您尚未绑定手机号

李昊哲-小课

Q: `nvidia-smi` 显示 CUDA 版本与安装的 CUDA Toolkit 版本不一致？

Q: 编译 CUDA 代码时找不到 `cuda.h` 或 `cudnn.h`？

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

Q: PyTorch 显示 `CUDA available: False`？

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

Q: TensorFlow 显示 `No GPU devices found`？

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

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