Fix 'Docker Desktop WSL 2 backend stopped' on Windows

Overview

When Docker Desktop shows “WSL 2 backend stopped” on Windows, it usually means the WSL 2 runtime or the Docker-managed WSL distributions (docker-desktop, docker-desktop-data) failed to start. Common causes include missing Windows features, outdated WSL kernel, low disk space, or a corrupted Docker Desktop WSL distro.

This guide walks through quick fixes, diagnostics, and safe recovery steps.

Quickstart (most issues fixed in 5–10 minutes)

1. Update WSL kernel and status.
   • PowerShell (Admin):

     wsl --status
     wsl --update
     wsl --shutdown
     

2. Ensure required Windows features.
   • PowerShell (Admin):

     dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
     dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
     

   • Restart Windows.
3. Set WSL 2 as default and verify distros:

   wsl --set-default-version 2
   wsl -l -v
   

4. Restart Docker Desktop and WSL services:

   wsl --shutdown
   Restart-Service LxssManager -Force
   Restart-Service com.docker.service -ErrorAction SilentlyContinue
   

5. Test a container:

   docker run --rm hello-world
   

If it runs, your backend is healthy. If not, continue below.

Minimal working example (MWE)

Build and run a tiny container to verify the backend:

Dockerfile:

FROM alpine:3.20
CMD ["/bin/sh", "-c", "echo WSL2 backend works"]

Build and run (PowerShell):

docker build -t wsl2-ok .
docker run --rm wsl2-ok

Expected output: WSL2 backend works

Step-by-step diagnostics and fixes

1. Check hardware virtualization and Windows version

   • PowerShell (Admin):

     Get-CimInstance Win32_Processor | Select-Object -ExpandProperty VirtualizationFirmwareEnabled
     

     If False, enable SVM/Intel VT-x in BIOS/UEFI.

2. Verify WSL feature state and kernel

   • Confirm features are enabled (see Quickstart step 2).
   • Update WSL kernel and shut down any running VMs:

     wsl --update
     wsl --shutdown
     wsl --status
     

3. Ensure your user distro is WSL 2

   • List and convert if needed:

     wsl -l -v
     wsl --set-version <YourDistroName> 2
     

4. Check disk space (host and docker-desktop-data)

   • Ensure the drive hosting your user profile and Docker data has free space (>5–10 GB recommended):

     Get-PSDrive -PSProvider FileSystem
     

   • Low space can prevent WSL VHDX expansion and stop the backend.

5. Restart services cleanly

   • Restart WSL and Docker services:

     wsl --shutdown
     Restart-Service LxssManager -Force
     Restart-Service com.docker.service -ErrorAction SilentlyContinue
     

   • Then restart Docker Desktop from the Start menu.

6. Reset WSL integration and networking (Docker Desktop UI)

   • Docker Desktop → Settings → Resources → WSL Integration:
     • Disable all distros, Apply & Restart.
     • Re-enable your working distro(s), Apply & Restart.
   • Docker Desktop → Troubleshoot → Restart Docker.

7. Repair .wslconfig (optional but helpful)

   • Create or edit %UserProfile%.wslconfig:

     [wsl2]
     memory=6GB
     processors=4
     swap=0
     localhostForwarding=true
     kernelCommandLine=cgroup_memory=1 cgroup_enable=memory
     

   • Apply changes:

     wsl --shutdown
     

8. Clear stale Docker resources (non-destructive)

   docker system prune --volumes --force
   docker builder prune --all --force
   

9. Last resort: rebuild Docker’s WSL distros (data loss for images/volumes)

   • This removes docker-desktop and docker-desktop-data and their contents.

   wsl --shutdown
   wsl -l -v
   wsl --unregister docker-desktop
   wsl --unregister docker-desktop-data
   

   • Start Docker Desktop; it will recreate the distros. Then re-pull images.

10. Validate with the MWE or hello-world

    docker run --rm hello-world
    

Pitfalls and common causes

• Missing Windows features: Both “Virtual Machine Platform” and “Windows Subsystem for Linux” must be enabled.
• Outdated WSL kernel: Newer Docker Desktop releases require recent kernels.
• Low disk space: The docker-desktop-data VHDX cannot expand and the backend exits.
• Antivirus/VPN drivers: Some network drivers and antivirus hooks interfere with WSL networking. Temporarily disable or add exclusions.
• Conflicting hypervisors: Legacy Hyper-V VMs, VirtualBox (older versions), or other hypervisors can conflict with WSL 2.
• Corporate proxies/firewalls: May block Docker’s internal services; set proper proxy in Docker Desktop and Windows environment if needed.

Performance notes (avoid backend stalls)

• Store project files inside WSL’s ext4 filesystem (e.g., \wsl$\Ubuntu\home<user>), not on C:\ via bind mounts. This improves I/O and stability.
• Use .wslconfig to cap memory/CPU to prevent host pressure while leaving enough RAM for Docker.
• Enable memory cgroups (kernelCommandLine above) for Kubernetes/Compose workloads.
• Prefer gRPC FUSE (Docker Desktop default) and recent WSL for better file sharing performance.
• Avoid massive bind mounts with millions of files; use .dockerignore and multi-stage builds to reduce context size.

Troubleshooting checklist

• wsl --status shows Default Version: 2 and a recent kernel.
• wsl -l -v shows docker-desktop and your distro in STATE: Running after starting Docker.
• Services LxssManager and com.docker.service are running.
• Host drive has sufficient free space.
• Minimal container runs successfully.

FAQ

• Do I need Hyper-V?

  • WSL 2 uses “Virtual Machine Platform”; enabling Hyper-V is not strictly required but typically compatible.

• Will unregistering docker-desktop delete my images and volumes?

  • Yes. Unregistering docker-desktop-data wipes Docker data. Back up first if needed.

• How do I view logs?

  • Docker Desktop → Troubleshoot → Get support to collect logs. You can also inspect Windows Event Viewer and WSL errors after wsl --shutdown.

• Can I run Docker Engine directly inside my Linux distro?

  • Yes, you can install Docker in a WSL distro and bypass Docker Desktop, but you’ll manage engine updates and integration yourself.

• The backend starts then stops again—what next?

  • Re-check disk space, update WSL, reduce memory pressure via .wslconfig, and temporarily disable VPN/AV to isolate conflicts.