From db1170e63af5d15ce59f76d7f8e5b763bd22e7be Mon Sep 17 00:00:00 2001 From: Jeffery Tse Date: Tue, 7 Jul 2026 01:02:55 -0400 Subject: [PATCH 1/2] fix(docker): detect snap+WSL2 GPU passthrough incompatibility, document fix --- docs/setup.md | 15 +++++++++++++ scripts/check-docker-gpu.sh | 42 +++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) diff --git a/docs/setup.md b/docs/setup.md index fd63e02a5..7f81556f8 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -151,6 +151,21 @@ scripts/check-docker-gpu.sh --enable-nvidia-overlay scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay ``` +> **WSL2 + snap Docker.** If `docker run --gpus all ...` fails with +> `failed to fulfil mount request: open /usr/lib/wsl/lib/libdxcore.so: no +> such file or directory`, check whether Docker was installed via `snap` +> (`snap list docker`, or `docker info --format '{{.DockerRootDir}}'` reports +> a path under `/var/snap/docker/`). Snap's confinement prevents Docker from +> seeing the GPU library WSL2 injects at `/usr/lib/wsl/lib`, even though the +> file exists on the host — installing or reconfiguring +> `nvidia-container-toolkit` will not fix this, since the toolkit isn't the +> problem. `scripts/check-docker-gpu.sh` detects this combination and calls +> it out directly. The fix is to remove snap Docker and install the official +> apt-based Docker Engine instead +> ([docs.docker.com/engine/install](https://docs.docker.com/engine/install/)), +> then re-run `nvidia-ctk runtime configure --runtime=docker` and restart +> Docker. + Safety notes: - The app never installs host GPU runtime automatically. - The app never edits `.env` automatically. diff --git a/scripts/check-docker-gpu.sh b/scripts/check-docker-gpu.sh index b80122ee2..d30d4c5f9 100755 --- a/scripts/check-docker-gpu.sh +++ b/scripts/check-docker-gpu.sh @@ -215,6 +215,28 @@ _check_nvidia_smi() { } # Returns 1 if Docker is unavailable (callers should stop further GPU checks). +# WSL2 only: Docker installed via snap confines the container runtime's mount +# namespace, so it cannot see the GPU library WSL2 injects at +# /usr/lib/wsl/lib/libdxcore.so even though the file exists on the host. +# Symptom: `docker run --gpus all ...` fails with +# "failed to fulfil mount request: open /usr/lib/wsl/lib/libdxcore.so: no +# such file or directory". No nvidia-container-toolkit install or +# `nvidia-ctk runtime configure` fixes this — the fix is to stop using the +# snap package. DockerRootDir is the reliable way to tell: snap installs +# report a path under /var/snap/docker/ instead of the normal /var/lib/docker. +_is_wsl() { + grep -qi microsoft /proc/version 2>/dev/null && return 0 + [ -d /usr/lib/wsl ] && return 0 + return 1 +} + +_is_docker_snap() { + case "$(docker info --format '{{.DockerRootDir}}' 2>/dev/null)" in + */snap/docker/*|*/snap.docker/*) return 0 ;; + esac + return 1 +} + _check_docker() { _info "Checking Docker..." if ! command -v docker >/dev/null 2>&1; then @@ -258,6 +280,26 @@ _check_gpu_passthrough() { echo _fail "GPU passthrough failed. Check these steps in order:" echo + if _is_wsl && _is_docker_snap; then + _warn "Detected: Docker installed via snap, running on WSL2." + _warn "This is a known incompatibility, not a toolkit/config problem:" + _warn " snap confines Docker's mount namespace, so it cannot see the" + _warn " WSL2-injected GPU library at /usr/lib/wsl/lib/libdxcore.so even" + _warn " though the file exists on the host. Installing/reconfiguring" + _warn " nvidia-container-toolkit will NOT fix this — the numbered" + _warn " steps below will not help until Docker itself is replaced." + echo + _info "Fix: remove snap Docker and install the official apt-based Docker" + _info "Engine instead (unsandboxed, can see /usr/lib/wsl/lib):" + echo + echo " sudo snap remove docker" + echo " # then follow: https://docs.docker.com/engine/install/ubuntu/" + echo " sudo nvidia-ctk runtime configure --runtime=docker" + echo " sudo systemctl restart docker" + echo + _info "Re-run this script afterward to confirm passthrough works." + echo + fi echo " 1. Install NVIDIA Container Toolkit (if not already installed):" echo " Arch: sudo pacman -S nvidia-container-toolkit" echo " Debian: sudo apt install nvidia-container-toolkit" From 109301be78ee9e0d4a0e72912d9d419aa166c0c0 Mon Sep 17 00:00:00 2001 From: RaresKeY <158580472+RaresKeY@users.noreply.github.com> Date: Wed, 8 Jul 2026 19:30:41 +0000 Subject: [PATCH 2/2] docs(docker): polish WSL2 snap GPU guidance --- docs/setup.md | 41 ++++++++++++++++++++++++------------- scripts/check-docker-gpu.sh | 14 ++++--------- 2 files changed, 31 insertions(+), 24 deletions(-) diff --git a/docs/setup.md b/docs/setup.md index 7f81556f8..963285f16 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -151,20 +151,33 @@ scripts/check-docker-gpu.sh --enable-nvidia-overlay scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay ``` -> **WSL2 + snap Docker.** If `docker run --gpus all ...` fails with -> `failed to fulfil mount request: open /usr/lib/wsl/lib/libdxcore.so: no -> such file or directory`, check whether Docker was installed via `snap` -> (`snap list docker`, or `docker info --format '{{.DockerRootDir}}'` reports -> a path under `/var/snap/docker/`). Snap's confinement prevents Docker from -> seeing the GPU library WSL2 injects at `/usr/lib/wsl/lib`, even though the -> file exists on the host — installing or reconfiguring -> `nvidia-container-toolkit` will not fix this, since the toolkit isn't the -> problem. `scripts/check-docker-gpu.sh` detects this combination and calls -> it out directly. The fix is to remove snap Docker and install the official -> apt-based Docker Engine instead -> ([docs.docker.com/engine/install](https://docs.docker.com/engine/install/)), -> then re-run `nvidia-ctk runtime configure --runtime=docker` and restart -> Docker. +**WSL2 + snap Docker.** If the NVIDIA check fails with this error, Docker may be +installed via snap: + +```text +failed to fulfil mount request: open /usr/lib/wsl/lib/libdxcore.so: no such file or directory +``` + +Check with `snap list docker` or: + +```bash +docker info --format '{{.DockerRootDir}}' +``` + +A Docker root under `/var/snap/docker/` means snap confinement can prevent +Docker from seeing WSL2's `/usr/lib/wsl/lib` GPU libraries even when the files +exist on the host. Reinstalling or reconfiguring `nvidia-container-toolkit` will +not fix that. Remove snap Docker, install the official apt-based Docker Engine +([Docker docs](https://docs.docker.com/engine/install/ubuntu/)), then configure +the NVIDIA runtime again: + +```bash +sudo snap remove docker +sudo nvidia-ctk runtime configure --runtime=docker +sudo systemctl restart docker +``` + +Then re-run `scripts/check-docker-gpu.sh`. Safety notes: - The app never installs host GPU runtime automatically. diff --git a/scripts/check-docker-gpu.sh b/scripts/check-docker-gpu.sh index d30d4c5f9..22e6eb539 100755 --- a/scripts/check-docker-gpu.sh +++ b/scripts/check-docker-gpu.sh @@ -214,16 +214,9 @@ _check_nvidia_smi() { echo } -# Returns 1 if Docker is unavailable (callers should stop further GPU checks). -# WSL2 only: Docker installed via snap confines the container runtime's mount -# namespace, so it cannot see the GPU library WSL2 injects at -# /usr/lib/wsl/lib/libdxcore.so even though the file exists on the host. -# Symptom: `docker run --gpus all ...` fails with -# "failed to fulfil mount request: open /usr/lib/wsl/lib/libdxcore.so: no -# such file or directory". No nvidia-container-toolkit install or -# `nvidia-ctk runtime configure` fixes this — the fix is to stop using the -# snap package. DockerRootDir is the reliable way to tell: snap installs -# report a path under /var/snap/docker/ instead of the normal /var/lib/docker. +# WSL2 snap Docker cannot see /usr/lib/wsl/lib/libdxcore.so from its confined +# namespace, so NVIDIA passthrough fails until the user switches to non-snap +# Docker. DockerRootDir identifies snap installs more reliably than snap(8). _is_wsl() { grep -qi microsoft /proc/version 2>/dev/null && return 0 [ -d /usr/lib/wsl ] && return 0 @@ -237,6 +230,7 @@ _is_docker_snap() { return 1 } +# Returns 1 if Docker is unavailable (callers should stop further GPU checks). _check_docker() { _info "Checking Docker..." if ! command -v docker >/dev/null 2>&1; then