wsl GPU passthrough with wslc: --gpus, CUDA and device access
wslc supports GPU passthrough through the same --gpus flag
you already use with Docker. No plugin, no toolkit installer, no container-toolkit package
to configure. WSL containers delegates to the Windows host GPU-PV (para-virtualisation)
layer, which is the same mechanism WSL 2 and Docker Desktop use.
Quick start
# verify the GPU is visible
wslc run --rm --gpus all nvidia/cuda:12.4-base nvidia-smi
# expected output:
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 560.94 Driver Version: 560.94 CUDA Version: 12.6 |
# +-----------------------------------------------------------------------------+Flag reference
| Flag | Works? | Notes |
|---|---|---|
--gpus all | Yes | Pass all GPUs to the container. |
--gpus '"device=0"' | Yes | Pass a specific GPU by index. |
--device nvidia.com/gpu=all | No | Not recognized. Use --gpus. |
--device /dev/dri | No | Generic device passthrough not implemented. |
What you do not need
Unlike Docker, there is no separate nvidia-container-toolkit to install.
The host GPU driver is all that is required. wslc picks it up through the same
GPU-PV path used by WSL 2, so if nvidia-smi works inside a WSL distro,
it works inside a wslc container too.
Common failures
ldconfig failed with status 0x100-
The container started but the host has no NVIDIA GPU. Remove
--gpusfrom the command. This is common on CI runners and cloud VMs without a GPU. Argument name was not recognized: '--device'-
--devicedoes not exist on wslc 2.9.4.0. Change it to--gpus. could not select device driver ""- The host NVIDIA driver is too old for the CUDA version in the image. Update the host driver or use an older CUDA base image.
Limitations
- Only NVIDIA GPUs are tested. AMD and Intel GPU support is unconfirmed.
- GPU hot-add (attaching a GPU to a running container) is not supported.
- No MIG (Multi-Instance GPU) configuration is exposed through the CLI.
- The GPU is accessed through GPU-PV, not PCIe passthrough, so CUDA profilers that require direct hardware access may not work.