Installing Docker Desktop with the WSL2 back end

miliarch -

Verify that your Windows 10 installation is version 2004 or later

  1. Click Start or press WINDOWS_KEY + R
  2. Type winver
  3. Press Enter
  4. 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

  1. Right click Windows taskbar
  2. Click Task Manager
  3. Click More details if only a list of processes appears
  4. Click Performance tab
  5. Select CPU
  6. 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

  1. Right click Start
  2. Click Apps and Features
  3. Click Programs and Features under Related Settings section
  4. Click Turn Windows features on or off
  5. Select Virtual Machine Platform if not already selected
  6. Select Windows Subsystem for Linux if not already selected
  7. 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

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

Configure WSL2 as default WSL version

  1. Right click Start
  2. Click Windows PowerShell (Admin)
  3. Accept the UAC prompt
  4. 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.

  1. Right click Start
  2. Click Windows PowerShell (Admin)
  3. Accept the UAC prompt
  4. Enter the following command to see existing WSL distributions and their current versions: wsl --list --verbose
  5. 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

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

Start and configure Docker Desktop

  1. Docker Desktop should launch automatically on sign-in - if it does not, launch it manually
  2. Right click the Docker whale icon in system tray
  3. Click Settings
  4. In General: Verify Use the WSL 2 based engine is selected
  5. 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

References

I used the following references to learn how to install Docker Desktop and WSL2:

This runbook started as a gist on GitHub - view it here: https://gist.github.com/miliarch/59953116f1e919b1e5ad4ed23fae7d29