How to Install Docker on Ubuntu WSL 2 in Windows 11

With the rise of Windows Subsystem for Linux (WSL 2), it's become easier for developers to run Linux environments on their Windows machines. One of the most common tools developers need is Docker, which allows for efficient containerization. In this article, we will cover how to install Docker in WSL 2 running Ubuntu on Windows 11.

Prerequisites

Before starting, ensure the following:

1. Windows 11: WSL 2 is available on Windows 11 (as well as Windows 10).

2. WSL 2 Installed: You should have WSL 2 enabled with Ubuntu already set up. If not, you can install Ubuntu WSL 2 by following this guide.

3. Ubuntu as the Default Distro: Ensure that Ubuntu is the default WSL distro by running the following command:

wsl -l -v

Step 1: Update Your Ubuntu Packages

To ensure you have the latest software versions, update the package index on your Ubuntu system:

sudo apt-get update

Upgrade existing packages:

sudo apt-get upgrade

Step 2: Install Required Dependencies

Before installing Docker, you need to install some prerequisite packages that Docker relies on:

sudo apt-get install ca-certificates curl gnupg lsb-release

Step 3: Add Docker’s Official GPG Key

Docker uses GPG keys to verify its packages. You need to add Docker’s official GPG key to your system:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Step 4: Set Up the Docker Repository

Now, you can add Docker’s official APT repository to your system:

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

Step 5: Install Docker Engine

With the repository added, update the package index and install Docker:

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

Step 6: Enable and Start Docker Service

Since WSL 2 does not run systemd by default, Docker might not start automatically. However, you can manually start Docker with the following command:

sudo service docker start

Step 7: Test the Docker Installation

To confirm that Docker is installed correctly, you can run a simple test by pulling and running the "hello-world" Docker container:

sudo docker run hello-world

This command will download a test image and run it in a container. If the installation was successful, you’ll see a message saying, "Hello from Docker!"

Step 8: Configure Docker to Start on WSL Boot (Optional)

To make Docker run automatically whenever your WSL instance starts, you can add the following configuration to your .bashrc or .profile:

sudo service docker start

Step 9: Optional Configuration for Non-Root Users

By default, Docker requires root privileges to run. If you want to run Docker as a non-root user, you need to add your user to the docker group:

sudo groupadd docker
sudo usermod -aG docker $USER

After adding the user to the group, either restart your WSL instance or run:

newgrp docker

Now, you can use Docker without having to prefix commands with sudo.

---

Troubleshooting Tips

• WSL 2 Network Issues: If you face networking problems with Docker containers, ensure your WSL 2 environment is properly configured. Sometimes, restarting WSL and Docker services can resolve issues.

• Permissions Issues: If you get permission errors when running Docker as a non-root user, ensure that you have logged out and back in after adding yourself to the docker group.

Conclusion

With Docker installed in WSL 2, you can now take full advantage of containerized applications directly from your Ubuntu distribution on Windows 11. Docker in WSL 2 provides a seamless Linux development experience while benefiting from Windows' host system.

---

This guide covers the essentials, but you can refer to the official Docker documentation for more detailed options and configurations.