【踩坑实录】WSL2 解决 onnxruntime\-gpu ImportError: libcudart\.so\.13 无 CUDA13 运行库问题

前言

近期在 Windows WSL2 Ubuntu 环境部署深度学习 ONNX 推理项目时，程序启动直接报错：libcudart.so.13: No such file or directory。

网上绝大多数教程仅适配 CUDA12，极少有 WSL2 下 CUDA13 完整适配方案，且存在大量错误安装方式（简写包名、混用Linux驱动、源不对等）。本文结合真实排错过程，给出 WSL2 下 CUDA13 唯一正确安装方式 + 兜底 CPU 平滑方案。

本文适配环境：WSL2(Ubuntu) + onnxruntime-gpu 1.27+ + Windows 显卡直通

一、完整报错信息

项目启动命令：

Plain 复制代码

PYTHONUNBUFFERED=1 python analysis_main.py --host 172.27.101.232 --port 8001 --simu 1

核心报错：

Plain 复制代码

ImportError: libcudart.so.13: cannot open shared object file: No such file or directory

报错栈定位：导入 onnxruntime-gpu 时，系统缺失 CUDA13 运行时动态库。

二、问题根因分析（关键）

1. 版本绑定关系

onnxruntime-gpu ≥ 1.27.0 ：强制依赖 CUDA 13.x
onnxruntime-gpu ≤ 1.26.0：依赖 CUDA 12.x

我的环境默认安装最新版 onnxruntime-gpu，系统内无 CUDA13，直接库文件缺失报错。

2. 为什么 `apt install cuda-toolkit-13` 报错找不到包？

这是全网高频坑：

错误命令：sudo apt install cuda-toolkit-13（简写大版本，APT 无法识别）
正确包名：cuda-toolkit-13-0（必须带小版本后缀）

3. WSL2 CUDA 特殊机制（必看）

WSL2 基于 Hyper-V 轻量虚拟化，GPU 直通规则和物理机 Linux 完全不同：

Windows 宿主机安装 NVIDIA 显卡驱动
WSL2 内禁止安装显卡驱动，会直接冲突
WSL2 仅需安装 CUDA Toolkit 运行/开发库 即可完成 GPU 直通

三、WSL2 安装 CUDA13 完整正确流程

Ubuntu 官方源无 CUDA13，必须手动添加 NVIDIA 官方 WSL 专属源。

步骤1：添加 NVIDIA CUDA 源密钥与仓库

Plain 复制代码

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

步骤2：安装 CUDA13.0 Toolkit（精准包名）

Plain 复制代码

sudo apt install cuda-toolkit-13-0 -y

默认安装路径：/usr/local/cuda-13.0

步骤3：配置动态库环境变量（解决 .so 文件找不到）

程序运行时依赖 LD_LIBRARY_PATH 检索 CUDA 动态库，必须配置：

Plain 复制代码

echo 'export LD_LIBRARY_PATH=/usr/local/cuda-13.0/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

步骤4：校验库文件是否安装成功

Plain 复制代码

ls /usr/local/cuda-13.0/lib64/libcudart.so*

正常输出如下即代表修复成功：

Plain 复制代码

libcudart.so.13  libcudart.so.13.0.115

四、环境验证：测试 ONNX GPU 可用性

进入 Python 虚拟环境，执行测试代码：

Plain 复制代码

import onnxruntime as ort
# 打印可用推理设备
print("可用推理设备：", ort.get_available_providers())

GPU 正常时输出：['CUDAExecutionProvider', 'CPUExecutionProvider']

五、极简兜底方案（开发首选，零报错）

如果只是本地调试、不需要 GPU 加速，没必要安装 CUDA13，直接替换为 CPU 版 onnxruntime 一劳永逸：

Plain 复制代码

# 激活虚拟环境
source .venv/bin/activate
# 卸载GPU版本
pip uninstall onnxruntime-gpu -y
# 安装纯净CPU版本
pip install onnxruntime

该方案彻底规避所有 CUDA 依赖，适合 90% 算法本地调试场景。

六、全网高频踩坑总结

包名错误 ：CUDA13 不能简写，必须使用 cuda-toolkit-13-0
源缺失：Ubuntu 默认源无 CUDA13，必须添加 NVIDIA 官方 WSL 源
环境变量缺失 ：不配置 LD_LIBRARY_PATH，系统无法识别 .so 库
环境混淆：WSL2 无需安装显卡驱动，仅 Windows 宿主提供驱动
版本不匹配：onnxruntime-gpu 新版绑定 CUDA13，旧版绑定 CUDA12，不可混用

七、结语

WSL2 做深度学习推理开发非常轻便，但 CUDA 版本绑定严格、包名规范苛刻。遇到 libcudart.so.13 报错，要么精准安装 CUDA13 运行库开启 GPU 推理，要么切换 CPU 版 ONNX 快速调试，根据业务场景选择即可。