Docker Desktop WSL 2 backend on Windows
Windows Subsystem for Linux (WSL) 2 is a full Linux kernel built by Microsoft, which lets Linux distributions run without managing virtual machines. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid maintaining both Linux and Windows build scripts. In addition, WSL 2 provides improvements to file system sharing and boot time.
Docker Desktop uses the dynamic memory allocation feature in WSL 2 to improve the resource consumption. This means Docker Desktop only uses the required amount of CPU and memory resources it needs, while allowing CPU and memory-intensive tasks such as building a container, to run much faster.
Additionally, with WSL 2, the time required to start a Docker daemon after a cold start is significantly faster.
Before you turn on the Docker Desktop WSL 2 feature, ensure you have:
- At a minimum WSL version 18.104.22.168., but ideally the latest version of WSL to avoid Docker Desktop not working as expected.
- Windows 10, version 21H2 or later, or Windows 11, version 21H2 or later. For more information, see System requirementsopen_in_new.
- Installed the WSL 2 feature on Windows. For detailed instructions, refer to the Microsoft documentationopen_in_new.
For a better experience on WSL, consider enabling the WSL autoMemoryReclaimopen_in_new setting available since WSL 1.3.10 (experimental).
This feature causes the Windows host to better reclaim unused memory inside the WSL virtual machine, thereby resulting in better memory availability to other host applications. This is particularly helpful with Docker Desktop, since otherwise the WSL VM may consume large amounts (GBs) of memory in the Linux kernel's page cache as Docker builds container images, without ever returning that memory to the host when it becomes unused inside the VM.
To avoid any potential conflicts with using WSL 2 on Docker Desktop, you must uninstall any previous versions of Docker Engine and CLI installed directly through Linux distributions before installing Docker Desktop.
Download and install the latest version of Docker Desktop for Windowsopen_in_new.
Follow the usual installation instructions to install Docker Desktop. Depending on which version of Windows you are using, Docker Desktop may prompt you to turn on WSL 2 during installation. Read the information displayed on the screen and turn on the WSL 2 feature to continue.
Start Docker Desktop from the Windows Start menu.
Navigate to Settings.
From the General tab, select Use WSL 2 based engine..
If you have installed Docker Desktop on a system that supports WSL 2, this option is turned on by default.
Select Apply & Restart.
docker commands work from Windows using the new WSL 2 engine.
WSL 2 adds support for "Linux distros" to Windows, where each distro behaves like a VM except they all run on top of a single shared Linux kernel.
Docker Desktop does not require any particular Linux distros to be installed. The
docker CLI and UI all work fine from Windows without any additional Linux distros. However for the best developer experience, we recommend installing at least one additional distro and enable Docker support:
Ensure the distribution runs in WSL 2 mode. WSL can run distributions in both v1 or v2 mode.
To check the WSL mode, run:
$ wsl.exe -l -v
To upgrade the Linux distro to v2, run:
$ wsl.exe --set-version (distro name) 2
To set v2 as the default version for future installations, run:
$ wsl.exe --set-default-version 2
When Docker Desktop starts, go to Settings > Resources > WSL Integration.
The Docker-WSL integration is enabled on the default WSL distribution, which is Ubuntuopen_in_new. To change your default WSL distro, run:
$ wsl --set-default <distro name>
Select Apply & Restart.
Docker Desktop installs two special-purpose internal Linux distros
docker-desktop-data. The first (
docker-desktop) is used to run the Docker engine (
dockerd) while the second (
docker-desktop-data) stores containers and images. Neither can be used for general development.