Docker Desktop on Windows runs its engine inside a WSL 2 distribution called docker-desktop [1]. If WSL 2 is missing, outdated, or can’t start a virtual machine, Docker never gets past “Starting the Docker Engine…”. It shows one of these instead:
- “WSL 2 installation is incomplete”: the message older Docker Desktop builds showed when the WSL 2 kernel component was missing.
- “Docker Desktop – Unexpected WSL error” with a code such as
Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED. Current Docker documentation lists this as a virtualization failure [3]. wsl -l -vshowsdocker-desktopas Stopped and it never comes up [3].
All three come down to the same handful of causes. Work through the fixes in order.
30-Second Quick Fix
1. Update WSL. Open PowerShell as Administrator and run:
wsl --update
wsl --shutdown
Docker documents wsl --update as the way to install or update WSL [2]. It pulls the current Store-delivered version of WSL [6]. Restart Docker Desktop afterwards.
2. Confirm hardware virtualization is on. Open Task Manager → Performance → CPU and check the virtualization status. This is the check Docker recommends [3]. If virtualization shows as disabled, reboot into your BIOS/UEFI and enable it. It’s usually labeled Intel VT-x or AMD SVM/AMD-V. Docker Desktop requires hardware virtualization to be enabled in BIOS/UEFI [2].
If Docker starts after these two steps, you’re done.
Why This Happens
Docker Desktop’s WSL 2 engine needs four things at once. A supported WSL version is the first: Docker requires WSL 2.1.5 or later [2]. Second, the Windows features Windows Subsystem for Linux and Virtual Machine Platform must be on [6]. Third, CPU virtualization has to be enabled in firmware. Fourth, the Windows hypervisor must be set to launch at boot [3]. If any one is missing, the docker-desktop VM can’t be created, and Docker reports the WSL installation as incomplete or the engine as stopped.
Method 1: Update WSL and Force Version 2
Check which WSL you have
wsl --version
If this prints no version details, you’re on the old inbox WSL that ships with Windows. Docker needs the newer Store version [2]. Install or update it from an elevated PowerShell:
wsl --update
Microsoft Store blocked by policy? Download the latest .msi installer from the official WSL releases page [7] and run it. Docker documents this as the alternative install path [2].
Make WSL 2 the default and check Docker’s distro
wsl --set-default-version 2
wsl -l -v
In the output, the docker-desktop row should show 2 in the VERSION column [3]. If one of your own distros is still on version 1, convert it:
wsl --set-version Ubuntu 2
Replace Ubuntu with the distro name shown by wsl -l -v [1].
Check your Windows version
Run winver. Docker’s WSL 2 backend requires Windows 10 22H2 (build 19045) or Windows 11 23H2 (build 22631) or later [2]. On an older build, run Windows Update first. No WSL fix will work until you do.
Method 2: Enable the Windows Features and the Hypervisor
If WSL is current but the VM still won’t start, Windows itself is blocking virtualization.
Enable WSL and Virtual Machine Platform
In an Administrator PowerShell, run both commands, then restart Windows [6]:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Microsoft’s troubleshooting guide pairs the error “Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS” with exactly this fix [5].
Make sure the hypervisor launches at boot
Something may have turned the hypervisor off: a gaming anti-cheat tool, an older VirtualBox setup, or a manual tweak. Check its launch setting:
bcdedit /enum | findstr -i hypervisorlaunchtype
If it doesn’t say Auto, set it back and restart [3][5]:
bcdedit /set hypervisorlaunchtype auto
Confirm Windows sees a hypervisor
systeminfo
Look at the Hyper-V Requirements section. When virtualization is working, it reports that a hypervisor has been detected [3].
“WSL 2 requires an update to its kernel component”
If wsl --set-default-version 2 prints this, the WSL 2 kernel itself is missing. The error links to aka.ms/wsl2kernel, which points to Microsoft’s kernel update package [5][6]. Running wsl --update from Method 1 usually fixes it. The manual package is the fallback when the Store path is unavailable.
Method 3: Reset Docker’s WSL Engine (Advanced)
Use this when WSL itself works (wsl -l -v lists your distros) but Docker’s own distro won’t start.
1. Make sure the WSL 2 engine is selected
In Docker Desktop, go to Settings → General and select Use WSL 2 based engine [1]. If your system fully supports WSL 2, this option is on by default and may be hidden [1].
2. Check the Windows Server service
Docker’s install requirements say the Windows Server service (LanmanServer) must be enabled and set to start automatically [2]. Privacy and “debloat” scripts often disable it:
Get-Service LanmanServer
Set-Service -Name LanmanServer -StartupType Automatic
Start-Service LanmanServer
3. Rule out antivirus virtualization conflicts
Docker documents that Avast can block the WSL VM with Wsl/Service/RegisterDistro/CreateVm/HCS/ERROR_NOT_SUPPORTED. The fix is to disable Avast’s hardware-assisted virtualization option [3]. Other security suites with their own hypervisor features can cause the same problem.
4. Use Docker’s Troubleshoot menu
Open the Troubleshoot (bug) icon in Docker Desktop. Work through these options in order, from least to most destructive [4]:
- Restart Docker Desktop.
- Reset to factory defaults: returns all Docker Desktop settings to their initial state.
- Clean up data: resets the disk image. This destroys all Docker containers and images [4]. Push or export anything you need first.
Before step 3, shut WSL down cleanly so nothing holds the disk image open:
wsl --shutdown
Docker stores its WSL 2 data in C:\Users\[USERNAME]\AppData\Local\Docker\wsl by default. You can move it under Settings → Resources → Advanced [1]. Moving it is worth doing if a nearly full system drive is part of the problem.
💡 Pro Tip: Stop WSL2 & Docker Engine Conflicts
Most of the failures above come from Docker sharing one WSL 2 VM, one hypervisor, and one set of virtualization settings with everything else on your machine: antivirus, other VMs, editor remote servers. If you keep losing hours to this, move container workloads off your laptop. A lightweight cloud development environment runs Docker on a clean Linux host, and your local editor connects to it over SSH.
Verify the Fix
- Check the WSL distros:
wsl -l -v
docker-desktop should show Running and version 2 [3].
- Confirm the engine answers and can run a container:
docker version
docker run --rm hello-world
docker version should print both a Client and a Server section. If the Server section errors out, the engine still isn’t up.
- Reboot once more and confirm Docker starts on its own. Some fixes, like
bcdeditand the DISM features, only take effect after a restart, and a fix that only works until the next reboot isn’t a fix.
FAQ
Q: Docker works now, but my editor’s WSL connection keeps dropping with socket code 1006. Same problem? Not quite. That’s usually a conflict between the editor’s remote extension and its WSL server, not Docker’s engine. If you use Cursor, see our guide to fixing Cursor’s WebSocket error 1006. It covers removing the conflicting WSL extension and resetting the remote server.
Q: I’m running Docker inside an Azure VM and get the virtualization error. What’s different? Docker inside a VM needs nested virtualization. Microsoft’s troubleshooting guide notes that Azure VMs must have Trusted Launch disabled for nested virtualization to work [5]. Fix that on the VM side. Nothing inside the guest will work until you do.
Q: Do I need Windows Pro? For Windows containers, yes. Docker says they require Pro or Enterprise [2]. For Linux containers on the WSL 2 engine, follow the edition and build requirements on Docker’s Windows install page [2].
Sources
- [1] Docker Docs: Docker Desktop WSL 2 backend on Windows. https://docs.docker.com/desktop/features/wsl/
- [2] Docker Docs: Install Docker Desktop on Windows (system requirements). https://docs.docker.com/desktop/setup/install/windows-install/
- [3] Docker Docs: Troubleshoot topics for Docker Desktop (virtualization, hypervisor, WSL errors). https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/
- [4] Docker Docs: Troubleshoot Docker Desktop (Troubleshoot menu: reset and clean up data). https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/
- [5] Microsoft Learn: Troubleshooting Windows Subsystem for Linux. https://learn.microsoft.com/en-us/windows/wsl/troubleshooting
- [6] Microsoft Learn: Manual installation steps for older versions of WSL. https://learn.microsoft.com/en-us/windows/wsl/install-manual
- [7] Microsoft WSL on GitHub: Releases. https://github.com/microsoft/WSL/releases