How to Install Docker in WSL2 without Docker Desktop

The introduction of Windows Subsystem for Linux (WSL) provided developers with a unique blend of Linux's robustness and Windows' familiarity. WSL2 further enhanced this by integrating a full Linux kernel experience directly within Windows, enabling seamless execution of most Linux tasks on Windows. For those new to WSL2 or who haven't installed it, a guide on installing WSL2 on Windows 10/11 is recommended.

Docker, on the other hand, is a powerful tool for managing diverse applications within isolated container environments. For an in-depth understanding of Docker's concepts and functionality, further exploration of its workings is encouraged.

Docker Desktop, with its graphical user interface (GUI), provides a user-friendly way to manage containers. While its visual representation of containers, images, volumes, and resources is appealing, many tasks can be efficiently managed via the terminal. Running a background GUI that consumes system resources for infrequent use might be considered unnecessary by some. Additionally, some users have reported system freezes linked to Docker Desktop, leading many to seek alternative installation methods. This guide details how to install Docker directly within WSL2, bypassing Docker Desktop.

Step 1: Uninstall Docker Desktop

If Docker Desktop is currently installed, it must be uninstalled first. Follow these steps:

1. From the Start Menu, navigate to Settings > Apps > Apps & features.
2. Locate and click on Docker Desktop.
3. Click Uninstall.
4. Follow the on-screen prompts to complete the uninstallation.

Ensure Docker Desktop is stopped before initiating the uninstallation. Once complete, you can proceed.

Preliminary Step: Update WSL2 for Systemd Support

Before installing Docker and Docker Compose, ensure your Windows Subsystem for Linux (WSL2) is updated to the latest version with systemd support. This crucial feature enables the automatic startup of the Docker daemon when WSL boots, significantly streamlining the Docker workflow.

The Challenge Before Systemd Support

Previously, running Docker in WSL2 required manual startup of the Docker daemon for each WSL terminal session. This proved cumbersome, particularly when managing multiple containerized projects. Workarounds often involved third-party tools like Docker Toolbox or custom shell scripts.

The Solution: Systemd Support in WSL2

Microsoft's introduction of systemd support for WSL2 has significantly enhanced the user experience. This feature automates Docker daemon startup upon WSL2 boot, eliminating manual daemon management and streamlining Docker workflows.

Updating WSL2 for Systemd Support

To update your WSL2 kernel to the latest version, use the Microsoft Store. Open the Microsoft Store from the Start Menu and search for 'WSL'. Even if WSL2 was initially installed by enabling it through Windows Features, updating via the Store ensures you receive the latest version. Click 'Get' to download and install the update.

Alternatively, update the built-in WSL by running the following command in PowerShell (as an administrator):

wsl --update

Once updated, proceed to the next step.

Step 2: Install Docker

Open your WSL2 distribution via Windows Terminal or the Start Menu. Then, update the package list and upgrade existing packages:

Ubuntu/Debian:

sudo apt update && sudo apt upgrade -y

Fedora:

sudo dnf update -y

Alpine:

apk update && apk upgrade

Install necessary packages to enable apt to use packages over HTTPS and add Docker's official GPG key:

sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

For Debian users: Replace ubuntu with debian in the GPG key URL.

Set up the stable Docker repository:

echo \
"deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
"$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update the package list once more, then install Docker Engine:

sudo apt update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

This command installs the latest Docker Engine and its dependencies (Containerd, Docker CLI, Docker Compose, etc.).

For Fedora users: Replace apt with dnf in the preceding commands.

Start and enable the Docker service:

sudo systemctl enable docker
sudo systemctl start docker

Verify the installation by running the hello-world image:

sudo docker run hello-world

If successful, you should see output similar to this:

Congratulations! Docker is now successfully installed in WSL2.

Common Issues and Solutions

Docker daemon not starting automatically on WSL2 boot

If the Docker daemon fails to start automatically on WSL2 boot, your WSL2 kernel may be outdated. Refer to the preliminary update step described earlier to ensure your WSL2 kernel is the latest version.

If updating WSL2 is not feasible, a workaround involves adding the following code snippet to your ~/.profile, ~/.zprofile, ~/.bashrc, or ~/.zshrc file:

if grep -q "microsoft" /proc/version > /dev/null 2>&1;
then
  if service docker status 2>&1 | grep -q "is not running";
  then
    wsl.exe --distribution "${WSL_DISTRO_NAME}" --user root \
    --exec /usr/sbin/service docker start > /dev/null 2>&1
  fi
fi

This script checks if the WSL2 distribution is running on a Microsoft kernel and if the Docker daemon is not active. If both conditions are met, it initiates the Docker daemon. This serves as a functional workaround, though it is not the ideal long-term solution.

Upon the first terminal opening after this change, a brief delay may occur. Subsequent sessions should operate smoothly. Note that closing the terminal does not stop Docker; you must manually stop it using sudo service docker stop, shut down WSL2 completely with wsl --shutdown, or restart your PC.

Error: Permission denied while trying to connect to Docker daemon.

This error typically indicates that your user lacks the required permissions to access the Docker daemon. To resolve this, add your user to the docker group:

sudo usermod -aG docker $USER

For the changes to take effect, log out and then log back in. Afterward, you will be able to execute Docker commands without sudo.

Error: Unable to locate package docker-ce.

This error suggests that the Docker repository configured in the installation steps is inaccessible. This might be due to a network issue. If the problem persists, verify that the repository URL is correct for your specific Linux distribution and re-examine the installation steps for any potential errors.

WSL2 Upgrade Issues

Should you face issues while upgrading your WSL2 kernel, consider these troubleshooting steps:

• Shut down WSL using wsl --shutdown in PowerShell (run as administrator) and retry the upgrade.
• Temporarily disable any VPN or firewall and attempt the upgrade again.
• Verify that your Windows version supports WSL2 and that virtualization is enabled in your BIOS settings.

This guide aims to provide a clear path for installing Docker in WSL2 without Docker Desktop. For any questions or suggestions, further resources or community forums may offer assistance.