Installing Docker Desktop with the WSL2 back end

Runbooks Aug 8, 2020

Verify that your Windows 10 installation is version 2004 or later

Click Start or press WINDOWS_KEY + R
Type winver
Press Enter
Ensure the Version string indicates Version 2004 or later, e.g.:

Microsoft Windows
Version 2004 (OS Build 19041.423)

If your version is below 2004, run Windows Update to upgrade.

Note: Both Windows 10 Home and Professional support the WSL2 backend.

Verify that your system is capable of virtualization

Right click Windows taskbar
Click Task Manager
Click More details if only a list of processes appears
Click Performance tab
Select CPU
Verify that Virtualization: Enabled is present under CPU graph

If Virtualization: Enabled is not present in Task Manager's performance monitor, your system does not support virtualization, either because your CPU doesn't support VT-x/VT-d or AMD-V, or because the relevant setting is not enabled in/supported by your system's BIOS. Refer to documentation for your CPU and motherboard to determine if virtualization is supported by your system components. It's fairly common for the BIOS level setting to be called "Intel Virtualization Technology" for modern Intel processors, and "SVM" for modern AMD processors, but the exact name of the setting varies widely between manufacturers and versions.

Install Docker Desktop WSL2 prerequisites

Right click Start
Click Apps and Features
Click Programs and Features under Related Settings section
Click Turn Windows features on or off
Select Virtual Machine Platform if not already selected
Select Windows Subsystem for Linux if not already selected
Click OK and restart when prompted if either feature was not already selected, otherwise features are already installed and you can exit without action

Update WSL2 Linux kernel

Navigate to: https://docs.microsoft.com/en-us/windows/wsl/wsl2-kernel
Download the latest WSL2 Linux kernel (wsl_update_x64.msi)
Run the installer and follow prompts to install

Configure WSL2 as default WSL version

Right click Start
Click Windows PowerShell (Admin)
Accept the UAC prompt
Enter the following command to set WSL2 as default system wide:

wsl --set-default-version 2

Example output:

PS C:\Windows\system32> wsl --set-default-version 2
For information on key differences with WSL 2 please visit https://aka.ms/wsl2

Optional: Convert current WSL distribution to WSL2

Note: This step is only required to integrate Docker Desktop with your legacy WSL distribution. Skip it if you don't have a current WSL distribution, already have a WSL2 distribution you intend to integrate with Docker Desktop, or don't require integration with Docker Desktop.

Right click Start
Click Windows PowerShell (Admin)
Accept the UAC prompt
Enter the following command to see existing WSL distributions and their current versions: wsl --list --verbose
Convert existing WSL distribution to WSL2 (assuming Name returned in previous command is Debian): wsl --set-version Debian 2

Example output:

PS C:\Windows\system32> wsl --list --verbose
  NAME      STATE           VERSION
* Debian    Stopped         1
PS C:\Windows\system32> wsl --set-version Debian 2
Conversion in progress, this may take a few minutes...
For information on key differences with WSL 2 please visit https://aka.ms/wsl2
Conversion complete.

Download and install Docker Desktop

Navigate to https://www.docker.com/products/docker-desktop
Click Download for Windows (stable)
When download is complete, launch Docker Desktop Installer.exe
Accept the UAC prompt
Ensure Enable WSL 2 Windows Features is selected
Click Ok
Click Close and log out
Log back in to Windows

Start and configure Docker Desktop

Docker Desktop should launch automatically on sign-in - if it does not, launch it manually
Right click the Docker whale icon in system tray
Click Settings
In General: Verify Use the WSL 2 based engine is selected
Optional: In Resources > WSL INTEGRATION: Toggle your WSL distribution of choice to On, then click Apply & Restart to enable use of docker commands in your WSL distribution