Troubleshooting Docker Desktop with WSL2 backend on Windows can become a challenge when faced with the error "WSL2 not installed." This guide dives into the symptoms, causes, and step-by-step fixes to resolve this issue and ensure Docker Desktop operates smoothly.
Symptom: WSL2 not installed error
When setting up Docker Desktop with the WSL2 backend on Windows, users may encounter the error message "WSL2 not installed." This prevents Docker from initializing properly and blocks access to containerized workflows.
Validate System Requirements for Docker Desktop
Before proceeding, ensure your system meets the following prerequisites:
prerequisites
- Operating System: Windows 11 (64-bit) version 21H2 or higher.
- WSL2 Feature: Must be enabled in the Windows Features menu.
- Hardware Requirements: 64-bit processor and a minimum of 4GB RAM.
Diagnosis: Common Causes of the Error
This error typically occurs due to one or more of the following issues:
Step-by-Step Fixes
Use the following steps to resolve the "WSL2 not installed" error.
steps
Enable Required Windows Features
- Open the Start Menu and search for
Turn Windows features on or off. - Check the boxes for:
- Windows Subsystem for Linux
- Virtual Machine Platform
- Click OK to confirm, then restart your computer.
bash# Enable WSL and Virtual Machine Platform via PowerShell dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart- Open the Start Menu and search for
Set WSL Default Version to 2
- Open PowerShell as Administrator and run:bash
# Set WSL to default version 2 wsl --set-default-version 2
- Open PowerShell as Administrator and run:
Update WSL Components
- Download and install the WSL Update package if necessary.
- After installation, update WSL with:bash
# Update WSL to the latest version wsl --update
Verify the WSL Version
- After making the changes, check the WSL status:bash
# Check WSL status and confirm the default version wsl --status
- After making the changes, check the WSL status:
Restart Your Computer
- Reboot your system to finalize the changes.
- If the issue persists, verify WSL settings in PowerShell again.
Verifying Docker Desktop Functionality
After resolving the WSL2 setup issue, ensure Docker Desktop works as expected.
Verification Commands
# Check Docker version
docker version
# Output: Displays Docker client and server versions
# List Docker images
docker images
# Output: Lists installed images (if any)
# Perform a test search for Docker images
docker search mysql
# Output: Displays a list of MySQL-related imagesOpen Docker Desktop and confirm it starts without errors. You can use its graphical interface to manage containers and images, or use the command line for further tests.
FAQ
Why does Docker Desktop require WSL2 instead of Hyper-V?
WSL2 provides a lightweight Linux kernel for maximum compatibility, whereas Hyper-V is mainly for virtual machines. Docker Desktop favors WSL2 for performance and ease of use.
How do I confirm WSL2 is properly installed?
Run wsl --status in PowerShell. The output should indicate WSL 2 as the default version and detail the installation status.
Do I need to reinstall Docker Desktop after enabling WSL2?
No, you usually don't need to reinstall Docker Desktop. Configuring WSL2 and rebooting the system is sufficient.
Can I use WSL1 instead of WSL2 for Docker Desktop?
No, Docker Desktop requires WSL2 as it provides the necessary kernel features for containerized environments.