Docker Desktop Not Working on Windows 11 (WSL Errors)

On Windows, Docker Desktop does not run containers itself; it runs them inside a small Linux virtual machine managed by WSL 2. So when Docker fails to start, shows “WSL needs updating”, or reports an error during WSL startup, the problem is WSL, not Docker. Fix WSL first — usually one command — and Docker follows.

Step 1: update WSL#

Open PowerShell as administrator:

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

“WSL needs updating” and “error during WSL startup” are both fixed by wsl --update far more often than not. WSL is now delivered through the Microsoft Store and updates separately from Windows, so a machine can be fully patched and still have an old WSL. After the update, wsl --shutdown stops every running instance so the new version loads; then start Docker Desktop again.

If wsl --update fails to download, install WSL from the Microsoft Store directly, or download the latest release from the WSL GitHub releases page.

Step 2: confirm WSL 2 and a working distribution#

wsl -l -v

You should see docker-desktop with version 2 once Docker has run successfully at least once. If the list is empty or says version 1:

wsl --set-default-version 2
wsl --install -d Ubuntu          # a distribution Docker can also integrate with

Docker Desktop needs WSL 2 specifically; WSL 1 does not support it.

Step 3: virtualisation#

WSL 2 needs hardware virtualisation enabled, and two Windows features turned on. Symptoms of it being off include “The virtual machine could not be started” and “Please enable the Virtual Machine Platform”.

# Check virtualisation is enabled at the firmware level
systeminfo | Select-String "Virtualization"
# Expect: Virtualization Enabled In Firmware: Yes

# Turn on the Windows features (then reboot)
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

If firmware virtualisation says No, it must be enabled in the BIOS or UEFI settings, usually under a name like Intel VT-x, AMD-V or SVM Mode. That is the one step this article cannot do for you.

Stuck on “Docker Desktop starting”#

When the whale icon spins forever, work through this in order, testing after each:

1. Quit Docker Desktop from the system tray, then wsl --shutdown, then start it again.
2. Restart the Windows service: Restart-Service com.docker.service in an administrator PowerShell.
3. In Docker Desktop, Troubleshoot, then Restart, then if needed Clean / Purge data. Purging deletes images and containers, so export anything you need first.
4. Reboot Windows. WSL occasionally needs it after an update.

The Docker Desktop logs are under %LOCALAPPDATA%\Docker\log; the file for the WSL back end names the failing step.

After a Windows update#

Feature updates sometimes reset the Virtual Machine Platform feature or roll back the WSL kernel. Running wsl --update and re-checking the two features above fixes it. If WSL distributions all vanished, they are usually still on disk; wsl --import can bring one back from its virtual disk file.

Disk space and memory#

WSL keeps Docker’s data in a virtual disk that grows but does not shrink automatically. A full disk shows up as containers failing to start or images failing to pull.

docker system df          # what is using space
docker system prune -a    # remove unused images, containers and build cache

To cap what WSL can use, create %USERPROFILE%\.wslconfig:

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

Then wsl --shutdown for it to take effect. Without a cap, WSL can claim most of the machine’s memory under load and Windows itself becomes sluggish.

Integration with your distribution#

Running docker inside Ubuntu-on-WSL and getting command not found means integration is off for that distribution. In Docker Desktop: Settings, Resources, WSL integration, enable it for the distribution, apply, then open a new WSL terminal.

Reinstalling, as a last resort#

1. Uninstall Docker Desktop from Settings, Apps.
2. wsl --unregister docker-desktop and wsl --unregister docker-desktop-data if they still exist.
3. Delete %APPDATA%\Docker and %LOCALAPPDATA%\Docker.
4. Reboot, then install the current Docker Desktop.

This is rarely needed. The WSL update and the virtualisation features cover most cases; do those first.

Where to go next#

• WSL not working after a Windows update — the underlying layer.
• Docker Desktop for beginners — once it starts.
• What is Docker and why use it? — the concepts.