Overview
This guide resolves the Windows error message: "WSL distro is stopped" when Docker Desktop cannot start. You’ll diagnose WSL state, restart the right services, fix version/config mismatches, and safely reset Docker’s WSL distros if needed.
Applies to: Windows 10/11, Docker Desktop using WSL 2, DevOps/Docker workflows.
Quickstart (most cases)
- Close Docker Desktop.
- Open PowerShell as Administrator and run:
wsl --status
wsl --update
wsl --shutdown
Restart-Service LxssManager
Stop-Service vmcompute -Force; Start-Service vmcompute
wsl -t docker-desktop 2>$null
wsl -t docker-desktop-data 2>$null
- Start Docker Desktop and wait for "Docker Desktop is running".
- Verify:
docker version
docker run --rm hello-world
If this fails, proceed to the detailed steps below.
Minimal working example (verification)
Once fixed, this tiny example confirms Docker+WSL is healthy.
- Create and run a simple container:
docker run --rm alpine:3.20 echo "WSL+Docker OK"
- Or build/run a minimal image:
# Dockerfile
FROM alpine:3.20
CMD ["/bin/sh", "-c", "echo minimal build works"]
docker build -t minimal:test .
docker run --rm minimal:test
Diagnostics
Run these to understand the current state.
# List WSL distros and versions
wsl -l -v
# Check WSL kernel and default
wsl --status
# Quick health check: can docker WSL distro start?
wsl -d docker-desktop echo ok
# Service status
Get-Service LxssManager, vmcompute | Format-Table -Auto
Look for:
- docker-desktop and docker-desktop-data present and at Version 2.
- LxssManager and vmcompute running.
- wsl --status shows a recent kernel and Default Version: 2.
Step-by-step fixes
- Ensure required Windows features are enabled
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -NoRestart
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart
# Optional if Hyper-V is used elsewhere
# Enable-WindowsOptionalFeature -Online -FeatureName Hyper-V -All -NoRestart
# Ensure hypervisor is enabled (requires reboot if it was Off)
bcdedit /set hypervisorlaunchtype Auto
Reboot if any feature changed.
- Update and restart WSL cleanly
wsl --update
wsl --shutdown
Restart-Service LxssManager
Stop-Service vmcompute -Force; Start-Service vmcompute
- Make sure all distros use WSL 2
# Set default to v2
wsl --set-default-version 2
# Convert any v1 distro (including your dev distro)
wsl --set-version <YourDistroName> 2
- Reset Docker’s WSL distros (non-destructive first)
# Stop the Docker WSL distros, then start Docker Desktop again
wsl -t docker-desktop 2>$null
wsl -t docker-desktop-data 2>$null
If Docker Desktop still won’t start, consider a clean reset of Docker’s own WSL distros. Note: unregistering docker-desktop-data deletes Docker images/volumes. Back up first.
- Backup containers/images you need:
# Inside running environment (if accessible)
docker save -o images.tar $(docker images --format "{{.Repository}}:{{.Tag}}")
docker volume ls
# Use docker run to export critical data from volumes if needed
- Last resort (data-destructive):
wsl --unregister docker-desktop
wsl --unregister docker-desktop-data
# Then open Docker Desktop to let it recreate them
- Disk space and VHDX health
Low disk space or a bloated VHDX can prevent startup.
# Check free space in docker-desktop-data
echo df -h | wsl -d docker-desktop-data sh
# Remove unused assets (non-destructive)
docker system prune -af --volumes
Ensure the host drive containing %LocalAppData%\Docker\wsl has sufficient free space.
- Networking, proxies, VPNs
- Temporarily disconnect VPNs and pause third-party firewalls.
- Clear and reset networking:
netsh winsock reset
ipconfig /flushdns
- If you use an HTTP proxy, configure Docker Desktop’s proxy settings or set environment variables for your distro.
- Time sync
Clock drift can break TLS to Docker services.
w32tm /resync
wsl --shutdown
Start-Service LxssManager
- Running Docker Engine directly in your WSL distro (alternative setup)
If you are not using Docker Desktop and instead run Docker Engine inside Ubuntu/Debian on WSL 2, ensure systemd or service management is configured.
- Enable systemd in your distro:
# /etc/wsl.conf
[boot]
systemd=true
Then restart WSL and start Docker:
wsl --shutdown
wsl -d <YourDistroName>
sudo systemctl enable --now docker
sudo docker run --rm hello-world
Performance notes
- Limit WSL 2 resource usage with a global config to avoid vmmem spikes:
# %UserProfile%\.wslconfig
[wsl2]
memory=6GB
processors=4
swap=2GB
localhostForwarding=true
Apply with:
wsl --shutdown
- Prefer WSL 2 over WSL 1 for Docker. Mixing WSL 1 distros with Docker Desktop can be slower and less reliable.
- Clean unused Docker data regularly to keep the docker-desktop-data VHDX small:
docker system prune -af --volumes
Common pitfalls
- Unregistering docker-desktop-data without backups leads to loss of images/volumes.
- Mixing Hyper-V and third-party hypervisors can conflict. Ensure only one stack controls virtualization.
- Stale corporate proxy settings can block Docker; keep them consistent across Windows, Docker Desktop, and your distro.
- Using WSL 1 distros with Docker Desktop can cause mount and networking issues; convert to WSL 2.
- Editing /etc/resolv.conf manually while WSL auto-generates it can be overwritten; use /etc/wsl.conf if you must customize.
FAQ
Docker Desktop says "WSL distro is stopped" at startup. What’s first to try?
- Run wsl --update, wsl --shutdown, restart LxssManager and vmcompute, then relaunch Docker Desktop.
Do I need Hyper-V enabled?
- Docker Desktop on WSL 2 primarily needs VirtualMachinePlatform and the Windows hypervisor. Full Hyper-V is optional.
Is there data loss risk when fixing this?
- Only if you unregister docker-desktop-data. Try non-destructive steps first and back up before resets.
How do I check that Docker’s WSL distros exist?
- wsl -l -v should list docker-desktop and docker-desktop-data at Version 2.
Can I run Docker Engine directly inside Ubuntu instead of Docker Desktop?
- Yes, but then manage it with systemd inside the distro and do not run Docker Desktop concurrently.
