Introduction

Running GPU-accelerated Docker containers on Windows requires WSL2, the NVIDIA GPU driver for WSL, and Docker Desktop with WSL2 backend enabled. The nvidia-docker runtime is not needed on WSL2 — the NVIDIA Container Toolkit integrates directly through Docker's --gpus flag. The GPU driver is installed on Windows only (not inside WSL), and Docker Desktop routes GPU access through WSL2's Linux kernel to your containers.

Prerequisites

• Windows 10 Build 21H2 or later (or Windows 11)
• WSL2 enabled with a Linux distribution (Ubuntu recommended)
• NVIDIA GPU with CUDA support (GTX 1060+ / RTX series / Tesla)
• NVIDIA GPU driver 510.06+ installed on Windows (includes WSL2 support)
• Docker Desktop 4.x with WSL2 backend enabled

Step 1: Install WSL2

1# Run in PowerShell as Administrator
2wsl --install
3
4# If WSL is already installed, update to WSL2
5wsl --set-default-version 2
6
7# Install Ubuntu
8wsl --install -d Ubuntu
9
10# Verify version
11wsl -l -v
12#   NAME      STATE    VERSION
13# * Ubuntu    Running  2

Step 2: Install NVIDIA GPU Driver (Windows Side Only)

Download and install the NVIDIA GPU driver from nvidia.com/drivers. The driver version must be 510.06 or higher — these include built-in WSL2 support. Do NOT install CUDA or GPU drivers inside the WSL2 distribution; the Windows driver handles everything.

# Verify driver in PowerShell
nvidia-smi
# Should show your GPU, driver version, and CUDA version

# Verify GPU access from inside WSL2
nvidia-smi
# Same output — WSL2 uses the Windows driver transparently

Step 3: Configure Docker Desktop

1. Open Docker Desktop Settings
2. General: Enable "Use the WSL 2 based engine"
3. Resources > WSL Integration: Enable integration for your Ubuntu distribution
4. Apply and restart Docker Desktop

# Verify Docker works inside WSL2
docker --version
docker run hello-world

Step 4: Run GPU Containers

1# Test GPU access in a container
2docker run --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
3
4# Run with specific GPUs
5docker run --gpus '"device=0"' nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
6docker run --gpus '"device=0,1"' nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
7
8# Run PyTorch with GPU support
9docker run --gpus all -it pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime python -c "
10import torch
11print(f'CUDA available: {torch.cuda.is_available()}')
12print(f'GPU: {torch.cuda.get_device_name(0)}')
13print(f'Memory: {torch.cuda.get_device_properties(0).total_mem / 1e9:.1f} GB')
14"
15
16# Run TensorFlow with GPU
17docker run --gpus all -it tensorflow/tensorflow:2.14.0-gpu python -c "
18import tensorflow as tf
19print(f'GPUs: {tf.config.list_physical_devices(\"GPU\")}')
20"

Docker Compose with GPU

1# docker-compose.yml
2version: "3.8"
3services:
4  ml-training:
5    image: pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
6    deploy:
7      resources:
8        reservations:
9          devices:
10            - driver: nvidia
11              count: all
12              capabilities: [gpu]
13    volumes:
14      - ./data:/workspace/data
15    command: python train.py

docker compose up

Installing NVIDIA Container Toolkit (Alternative to Docker Desktop)

If you use the Docker Engine inside WSL2 directly (without Docker Desktop), install the NVIDIA Container Toolkit:

1# Inside WSL2 Ubuntu
2distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
3curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
4curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
5  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
6  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
7
8sudo apt-get update
9sudo apt-get install -y nvidia-container-toolkit
10sudo nvidia-ctk runtime configure --runtime=docker
11sudo systemctl restart docker
12
13# Test
14docker run --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

Troubleshooting

1# Check if WSL2 sees the GPU
2wsl nvidia-smi
3# If "command not found": Windows NVIDIA driver is too old or not installed
4
5# Check Docker GPU runtime
6docker info | grep -i runtime
7# Should list "nvidia" or show GPU support
8
9# Check CUDA version compatibility
10nvidia-smi  # Shows driver CUDA version (e.g., 12.2)
11# Container CUDA must be <= driver CUDA version
12
13# WSL2 kernel version check
14uname -r
15# Should show 5.10.x or higher with "microsoft" in the name
16
17# Reset WSL2 if GPU stops working
18wsl --shutdown
19# Then restart WSL2 and Docker Desktop

Common Pitfalls

• Installing NVIDIA drivers inside WSL2: The GPU driver must be installed on Windows only. WSL2 uses the Windows driver through a special kernel interface. Installing a Linux NVIDIA driver inside WSL2 conflicts with the passthrough driver and breaks GPU access. If you did this, uninstall the Linux driver with sudo apt remove --purge nvidia-*.
• Using nvidia-docker or nvidia-docker2 package on WSL2: The legacy nvidia-docker wrapper is deprecated. On WSL2, use docker run --gpus all directly. The NVIDIA Container Toolkit handles GPU passthrough through Docker's native --gpus flag without needing a separate runtime wrapper.
• CUDA version mismatch between driver and container: The container's CUDA version must be less than or equal to the driver's CUDA version. Running nvidia/cuda:12.2.0-base on a driver that supports CUDA 11.8 fails. Check your driver's CUDA version with nvidia-smi and use matching container tags.
• Docker Desktop WSL integration not enabled for the right distribution: Docker Desktop must have WSL integration enabled for the specific distribution you are using. Go to Settings > Resources > WSL Integration and toggle on your Ubuntu distribution. Without this, docker commands inside WSL2 fail with "command not found."
• WSL2 kernel too old for GPU support: GPU passthrough requires WSL2 kernel 5.10.43.3 or later. Run uname -r inside WSL2 to check. Update with wsl --update from PowerShell if the kernel is outdated. Older kernels do not have the /dev/dxg device needed for GPU access.

Summary

• Install the NVIDIA GPU driver on Windows only (510.06+), never inside WSL2
• Enable WSL2 backend in Docker Desktop and turn on integration for your distribution
• Use docker run --gpus all to pass GPUs into containers — no nvidia-docker needed
• Match container CUDA versions to your driver's maximum supported CUDA version
• Use nvidia-smi both inside WSL2 and inside containers to verify GPU access at each layer