Skip to content

WINDOWS-WSL2-GPU-GUIDE.md

Latest commit

 

History

History
282 lines (203 loc) · 6.62 KB

WINDOWS-WSL2-GPU-GUIDE.md

File metadata and controls

282 lines (203 loc) · 6.62 KB

Windows WSL2 GPU Guide for Dream Server

Complete guide for running Dream Server on Windows with WSL2 and NVIDIA GPU passthrough. AMD Strix Halo installs also use Docker Desktop + WSL2 for the service stack, but local inference runs through the Windows host accelerated path selected by install.ps1.

Quick Verification

After installation, verify GPU is accessible:

# In PowerShell (Windows side)
wsl nvidia-smi

# In WSL Ubuntu
wsl
nvidia-smi

# In Docker container
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

All three should show your GPU. If any fail, see troubleshooting below.

Prerequisites

Required

  • Windows 10 version 2004+ (build 19041) or Windows 11
  • WSL2 enabled
  • Docker Desktop with WSL2 backend
  • NVIDIA GPU with 8GB+ VRAM
  • Latest NVIDIA drivers (Game Ready or Studio)

Not Required (Common Mistake)

  • Do NOT install NVIDIA drivers inside WSL2 — Windows drivers provide GPU access to WSL2
  • Do NOT install CUDA toolkit in WSL2 — containers include their own CUDA

Installation Steps

Step 1: Enable WSL2

# Run as Administrator in PowerShell
wsl --install

Restart when prompted. This installs WSL2 and Ubuntu by default.

Verify:

wsl --status
# Should show: Default Version: 2

Step 2: Install Docker Desktop

  1. Download from https://docker.com/products/docker-desktop
  2. During install, check "Use WSL2 instead of Hyper-V"
  3. After install, verify WSL2 backend:
    • Open Docker Desktop → Settings → General
    • Confirm "Use the WSL2 based engine" is checked

Step 3: Install NVIDIA Drivers

Download latest drivers from https://www.nvidia.com/drivers

Verify driver includes WSL2 support:

# Driver version 465.21 or later includes WSL2 support
# Game Ready drivers work fine for compute

Step 4: Run Dream Server Installer

git clone https://github.com/Light-Heart-Labs/DreamServer.git
cd DreamServer
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1

Common Issues

Issue: "nvidia-smi not found" in WSL2

Cause: WSL2 doesn't have GPU support enabled or NVIDIA driver missing.

Fix:

# On Windows side — check driver
nvidia-smi
# If this fails, install NVIDIA drivers on Windows

# Verify WSL2 has GPU support
wsl cat /proc/driver/nvidia/version
# Should show driver version

Issue: GPU works in WSL2 but not in Docker

Symptoms:

  • wsl nvidia-smi shows GPU ✓
  • docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi fails ✗

Cause: Docker Desktop not using WSL2 backend.

Fix:

  1. Open Docker Desktop
  2. Settings → General → Check "Use the WSL2 based engine"
  3. Settings → Resources → WSL Integration → Enable integration with your distro
  4. Click "Apply & Restart"

Verify:

docker info | findstr WSL
# Should show: WSL2: true

Issue: "GPU access blocked by the operating system"

Symptoms:

docker: Error response from daemon: OCI runtime create failed: 
container_linux.go:380: starting container process caused: 
process_linux.go:545: container init caused: Running hook #0:: 
error running hook: exit status 1, stderr: nvidia-container-cli: 
initialization error: driver rpc error: failed to process request

Cause: Windows Defender or other security software blocking GPU access.

Fix:

  1. Add Docker Desktop to Windows Defender exclusions:

    • Windows Security → Virus & threat protection → Manage settings
    • Add or remove exclusions → Add an exclusion → Folder
    • Add C:\Program Files\Docker

  2. If using third-party antivirus, temporarily disable or add similar exclusion.

  3. Restart Docker Desktop.

Issue: CUDA version mismatch errors

Symptoms:

nvidia-container-cli: requirement error: unsatisfied condition: cuda>=11.6

Cause: Windows NVIDIA driver is too old for the container's CUDA version.

Fix: Update NVIDIA drivers on Windows side. The driver in WSL2 comes from Windows — you don't install CUDA drivers in WSL2.

Issue: Out of memory errors

Cause: WSL2 defaults to using 50% of available RAM.

Fix: Create .wslconfig to increase memory:

# In PowerShell (Windows side)
notepad "$env:USERPROFILE\.wslconfig"

Add:

[wsl2]
memory=24GB
processors=8
swap=4GB

Save, then:

wsl --shutdown
# Restart WSL2

Issue: PowerShell execution policy blocks script

Symptoms:

.\install.ps1 : File cannot be loaded because running scripts is disabled on this system.

Fix (temporary, per-session): run the installer through a one-shot bypass:

powershell -ExecutionPolicy Bypass -File .\install.ps1

Performance Tuning

Optimal .wslconfig for Dream Server

Create %USERPROFILE%\.wslconfig:

[wsl2]
# Memory: Leave 4-8GB for Windows, rest for WSL2
memory=20GB
processors=8
swap=4GB
swapFile=C:\temp\wsl-swap.vhdx
localhostForwarding=true
# Disable Windows interoperability if not needed (slight performance gain)
# interop.enabled=false

After editing:

wsl --shutdown
# WSL2 will restart with new settings

Docker Desktop Resource Limits

  1. Open Docker Desktop
  2. Settings → Resources → Advanced
  3. Set:
    • CPUs: 75% of available cores
    • Memory: 75% of available RAM
    • Swap: 2GB

Verification Checklist

Before reporting issues, verify:

  • Windows 10 build 19041+ or Windows 11
  • wsl --status shows Default Version: 2
  • wsl nvidia-smi shows GPU info
  • Docker Desktop is running
  • Docker Desktop uses WSL2 backend (Settings → General)
  • WSL integration enabled for Ubuntu (Settings → Resources → WSL Integration)
  • docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi shows GPU

Quick Commands Reference

# Restart WSL2 (fixes many issues)
wsl --shutdown

# Check WSL2 distros
wsl -l -v

# Set WSL2 as default
wsl --set-default-version 2

# Check Docker WSL2 backend
docker info | findstr WSL

# View WSL2 logs (for debugging)
Get-Content "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState\ext4.vhdx"

Getting Help

If you've verified the checklist and still have issues:

  1. After install, run diagnostics: cd $env:USERPROFILE\dream-server; .\dream.ps1 report
  2. Check WSL2 GPU issues: https://github.com/microsoft/WSL/issues?q=label%3Agpu
  3. Dream Server Discord: https://discord.gg/clawd

When reporting issues, include:

  • Output of wsl nvidia-smi
  • Output of docker info | findstr WSL
  • Windows build number: winver
  • Docker Desktop version