Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker Desktop on Windows stays on starting or shows a WSL error

ErrorDocker Desktop - Unexpected WSL error

Short answer

On Windows, a failed start is nearly always virtualization. Check that it is on in the BIOS, that Virtual Machine Platform and WSL are enabled, and that the hypervisor launches at boot. Then check antivirus conflicts, and that your user is in the docker-users group.

  • Applies to Windows 11, Docker Desktop 4, WSL 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    From PowerShell, confirm that WSL 2 itself works and that a hypervisor is detected. If the first line fails, Docker Desktop cannot start either.

    wsl -d docker-desktop echo WSL 2 is working
    systeminfo | findstr /i hypervisor
  2. 2Match what you see, then jump to its fix

    1. 1HCS_E_HYPERV_NOT_INSTALLED or ERROR_NOT_SUPPORTED in the errorVirtualization, WSL 2 or Hyper-V is offFix
    2. 2Wsl/Service/RegisterDistro/CreateVm/HCS/ERROR_NOT_SUPPORTED, often right after a Windows updateAntivirus software conflicts with Hyper-VFix
    3. 3Docker Desktop - Access Denied dialog at startupYour user is not in the docker-users groupFix

What does the error look like?

  • Docker Desktop - Unexpected WSL error
  • HCS_E_HYPERV_NOT_INSTALLED
  • Wsl/Service/RegisterDistro/CreateVm/HCS/ERROR_NOT_SUPPORTED
  • Docker Desktop - Access Denied

Cause 1 of 3

Virtualization, WSL 2 or Hyper-V is off

1Check

Causes are virtualization off in the BIOS, missing Windows features, or software that disabled Hyper-V. A hypervisor message in systeminfo means virtualization is on.

bcdedit /enum | findstr -i hypervisorlaunchtype

2Fix

Turn on virtualization in the BIOS and enable Virtual Machine Platform and Windows Subsystem for Linux. If the hypervisor does not launch at boot, set it to auto from an administrative prompt and restart.

bcdedit /set hypervisorlaunchtype auto

3Verify

After the restart, the WSL test line works.

wsl -d docker-desktop echo WSL 2 is working

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

Antivirus software conflicts with Hyper-V

1Check

Some antivirus products clash with Hyper-V. In Avast the culprit is hardware-assisted virtualization.

systeminfo | findstr /i hypervisor

2Fix

Temporarily uninstall the antivirus software or add Docker to its exclusions. For Avast, clear Enable hardware-assisted virtualization under Menu, Settings, Troubleshooting.

# Avast: Menu > Settings > Troubleshooting > Enable hardware-assisted virtualization (clear)

3Verify

Restart Docker Desktop.

wsl -d docker-desktop echo WSL 2 is working

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Your user is not in the docker-users group

1Check

Open Computer Management as administrator and look at Local Users and Groups > Groups > docker-users.

# Computer Management > Local Users and Groups > Groups > docker-users

2Fix

Add your account to the docker-users group, then sign out and back in.

# Add your user to docker-users, then sign out and back in

3Verify

After signing in again, start Docker Desktop.

wsl -d docker-desktop echo WSL 2 is working

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Restart Windows after enabling Hyper-V or WSL features.
  • Check Docker's antivirus notes before a large Windows update.
  • Run Docker Desktop in a VM only with nested virtualization on.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.