WSL + Docker GPU 环境排查：NVIDIA-SMI couldn't find libnvidia-ml.so 问题分析与解决

在使用 Windows Subsystem for Linux + Docker 的 GPU 环境时，经常会遇到一个看似简单却比较隐蔽的问题：

NVIDIA-SMI couldn't find libnvidia-ml.so library in your system.

一个典型现象是：

• WSL 主机中 nvidia-smi 正常
• Docker 容器中 nvidia-smi 失败

本文通过一个真实排查案例，分析问题根因，并给出解决方案。

---

一、问题现象

在 WSL 主机中运行：

nvidia-smi

输出正常，例如：

NVIDIA-SMI 581.32
GPU: NVIDIA GeForce RTX 3070 Ti

但进入 Docker 容器后运行：

nvidia-smi

却出现：

NVIDIA-SMI couldn't find libnvidia-ml.so library in your system

---

二、WSL GPU 的工作原理

WSL 的 GPU 机制与普通 Linux 不同。

GPU 驱动实际上运行在 Windows 内核 中，WSL 只是通过共享库访问 GPU。

整体架构如下：

关键点：

• GPU 驱动在 Windows
• WSL 通过 /usr/lib/wsl/lib 访问 GPU
• Docker GPU runtime 会 自动把这些库挂载到容器

---

三、第一步排查：WSL GPU 是否正常

在 WSL 主机检查：

ls /usr/lib/wsl/lib

正常应该看到：

libcuda.so
libnvidia-ml.so
libnvcuvid.so
nvidia-smi

例如：

ls /usr/lib/wsl/lib

输出：

libcuda.so
libcuda.so.1
libnvidia-ml.so.1
nvidia-smi

说明：

• Windows 驱动正常
• WSL GPU passthrough 正常

---

四、第二步排查：Docker GPU runtime

检查 NVIDIA runtime：

docker info | grep runtime

应看到：

Runtimes: runc nvidia

或查看 toolkit：

nvidia-container-cli -k -d /dev/tty info

如果能识别 GPU，例如：

Model: NVIDIA GeForce RTX 3070 Ti
CUDA version: 13.0

说明：

• NVIDIA Container Toolkit 工作正常

---

五、第三步排查：容器内 GPU 库

进入容器：

ls /usr/lib/wsl/lib

如果只看到：

libdxcore.so

而没有：

libcuda.so
libnvidia-ml.so

说明：

GPU runtime 没有成功挂载 WSL GPU 库。

---

六、根因分析

问题的真正原因通常是：

Docker 镜像内部已经包含 /usr/lib/wsl/lib 目录。

例如：

/usr/lib/wsl/lib/libdxcore.so

当目录已经存在时，NVIDIA runtime 不会再覆盖挂载 GPU 库。

因此容器最终看到的只是镜像中的内容。

这一过程如下：

最终结果：

容器无法访问：

libnvidia-ml.so

从而导致 nvidia-smi 失败。

---

七、解决方案

最直接的解决方案是 手动挂载 WSL GPU 库。

修改 docker run：

docker run -it \
  --gpus all \
  -v /usr/lib/wsl/lib:/usr/lib/wsl/lib \
  -e LD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH \
  your_image

关键参数：

-v /usr/lib/wsl/lib:/usr/lib/wsl/lib

以及：

-e LD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH

---

八、验证 GPU 是否正常

进入容器：

ls /usr/lib/wsl/lib

应看到：

libcuda.so
libnvidia-ml.so
nvidia-smi

再运行：

nvidia-smi

即可看到 GPU 信息。

---

九、完整 GPU 数据路径

整个 GPU 调用链如下：

---

十、常见 GPU 容器问题总结

问题	原因
nvidia-smi 找不到	GPU runtime 未启用
/dev/nvidia0 不存在	Docker 未使用 --gpus all
libnvidia-ml.so 缺失	WSL GPU 库未挂载
WSL GPU 正常但容器失败	镜像覆盖 /usr/lib/wsl

---

十一、实践建议

在 WSL + Docker GPU 环境中：

1️⃣ 不要在容器内安装 NVIDIA driver
2️⃣ 优先使用官方 CUDA 镜像
3️⃣ 避免镜像包含 /usr/lib/wsl
4️⃣ 必要时手动挂载 GPU runtime 库

---

十二、总结

本问题的本质是：

Docker 镜像中的 /usr/lib/wsl/lib 目录覆盖了 NVIDIA runtime 的 GPU 库挂载。

解决方法：

-v /usr/lib/wsl/lib:/usr/lib/wsl/lib

通过手动挂载 WSL GPU 库，即可恢复容器 GPU 功能。

---