Running Linux Containers Using WSL2: A Complete Guide for Windows Users

Introduction

Docker, with its containerization technology, has revolutionized the way developers build, ship, and run applications. Traditionally, Docker was synonymous with Linux environments, but thanks to advancements like Windows Subsystem for Linux 2 (WSL2), running Linux-based Docker containers on Windows has become much more seamless and efficient. With WSL2, Windows users can leverage a lightweight Linux kernel and run Linux containers natively on their Windows machines without needing a virtual machine or dual boot.

In this comprehensive guide, we'll explore how to set up WSL2 on Windows, configure Docker to work with WSL2, and run Linux containers efficiently. Whether you're a Windows user looking to dive into the world of Linux containers or a developer aiming to create a development environment that works across platforms, this guide has you covered.

1. What is WSL2?

Windows Subsystem for Linux 2 (WSL2) is a lightweight compatibility layer that allows Windows users to run a full Linux kernel directly on their Windows machines. WSL2 uses a virtualized Linux kernel, but it is significantly more efficient than traditional virtual machines because it has direct access to your hardware.

WSL2 allows Windows users to run Linux distributions like Ubuntu, Debian, and Fedora side-by-side with their Windows environment. One of the primary benefits of WSL2 is its ability to run Linux-based Docker containers natively without the overhead of a full virtual machine. This makes it an ideal choice for developers who need to work with both Windows and Linux tools.

2. Why Use WSL2 for Linux Containers on Windows?

There are several reasons why developers choose WSL2 to run Linux containers on Windows:

Native Linux Kernel: WSL2 includes a real Linux kernel, which allows you to run Linux applications and Docker containers as if you were on a Linux system.
Performance: Compared to traditional virtual machines, WSL2 is much faster, thanks to its lightweight design. It also has much lower resource consumption.
Seamless Integration: WSL2 integrates tightly with Windows, allowing you to access Windows files from the Linux environment and vice versa. This makes it easy to use your existing tools and workflows.
No Hyper-V Requirement: Unlike other virtualization technologies, WSL2 doesn't require Hyper-V. This means it can run on Windows versions like Windows 10 Home, which do not support Hyper-V.
Run Linux Containers: WSL2 allows Docker Desktop to run Linux containers natively on Windows, eliminating the need for a virtual machine or remote server for containerized workloads.

3. Setting Up WSL2 on Windows

Before running Linux containers on Docker with WSL2, you first need to set up WSL2 on your Windows machine. Here are the steps to get WSL2 up and running:

Step 1: Enable WSL on Windows

Open PowerShell as an administrator. You can do this by searching for "PowerShell" in the Start menu, right-clicking, and selecting "Run as administrator".

Run the following command to enable WSL:

wsl --install

This command will automatically enable WSL and install the default Linux distribution (usually Ubuntu).

Step 2: Set WSL2 as the Default Version

To ensure that WSL2 is used instead of WSL1, set it as the default version by running the following command:

wsl --set-default-version 2

This ensures that all future Linux distributions will use WSL2 by default.

Step 3: Install a Linux Distribution

You can install various Linux distributions from the Microsoft Store. Follow these steps:

Open the Microsoft Store on your Windows machine.
Search for a Linux distribution such as Ubuntu, Debian, or Fedora.
Click Install to install the distribution.

Once the installation is complete, you can launch the Linux distribution from the Start menu.

Step 4: Verify WSL2 Installation

To confirm that your Linux distribution is running on WSL2, open PowerShell and run the following command:

wsl -l -v

You should see output similar to the following, indicating that your distribution is using WSL2:

  NAME      STATE           VERSION
* Ubuntu    Running         2

4. Installing Docker and Configuring it with WSL2

Now that WSL2 is set up, let's install Docker and configure it to use WSL2 as the backend for Linux containers.

Step 1: Install Docker Desktop for Windows

Download the Docker Desktop Installer from the official Docker website: https://www.docker.com/products/docker-desktop.
Run the installer and follow the installation steps.
During the installation process, ensure that the option "Install required Windows components for WSL 2" is selected.

Step 2: Configure Docker to Use WSL2

Once Docker Desktop is installed, open Docker Desktop.
Navigate to Settings by clicking the gear icon in the top-right corner.
Under the General tab, ensure that the option "Use the WSL 2 based engine" is enabled.
Navigate to the Resources > WSL Integration tab, and enable Docker integration with your preferred WSL2 Linux distribution (e.g., Ubuntu). This allows Docker to run seamlessly within the WSL2 environment.

Step 3: Restart Docker Desktop

After configuring Docker Desktop to use WSL2, you may need to restart Docker Desktop for the changes to take effect. Right-click the Docker icon in the system tray and select Quit Docker Desktop, then relaunch it.

5. Running Linux Containers Using WSL2

Once Docker is set up with WSL2, you can start running Linux containers directly on your Windows machine. Here's how to get started:

Step 1: Open a Linux Shell

Open your WSL2 Linux distribution (e.g., Ubuntu) from the Start menu. You can also use Windows Terminal if you have multiple shells configured.

Step 2: Pull a Linux Container Image

You can pull Docker images from Docker Hub, the official Docker image repository. To pull a Linux-based image (e.g., Ubuntu), run the following command:

docker pull ubuntu

Docker will download the Ubuntu image from Docker Hub and store it on your system.

Step 3: Run a Linux Container

Now that the image is pulled, you can run a Linux container using the following command:

docker run -it ubuntu bash

This command starts an interactive Ubuntu container and drops you into the container's shell. You can now run commands as if you were in a Linux environment.

Step 4: List Running Containers

To see all running containers, use the following command:

docker ps

To list both running and stopped containers:

docker ps -a

6. Using Docker with WSL2: Basic Commands

Here are some basic Docker commands you can use to manage containers and images in WSL2:

Pull an Image: docker pull <image-name>
Run a Container: docker run <image-name>
List Running Containers: docker ps
Stop a Container: docker stop <container-id>
Remove a Container: docker rm <container-id>
List Docker Images: docker images
Remove an Image: docker rmi <image-id>

These commands are the foundation for working with Docker in a WSL2 environment.

7. Best Practices for Working with Docker and WSL2

Here are some best practices to follow when working with Docker and WSL2 on Windows:

Use WSL2 for Linux Containers: Always ensure that Docker is using WSL2 as the backend for Linux containers for optimal performance.
Choose the Right Linux Distribution: Some Linux distributions may work better for specific workflows. Ubuntu is a popular choice for development, but you can experiment with others.
Leverage Windows/Linux Integration: Take advantage of the seamless integration between Windows and WSL2 by sharing files and using tools across both environments.
Monitor Resource Usage: While WSL2 is efficient, it's still important to

monitor resource usage, especially when running multiple containers.

8. Troubleshooting Common Issues

Here are some common issues you may encounter when running Docker with WSL2 and how to resolve them:

Issue: Docker Desktop not starting or hangs on startup
- Solution: Try restarting Docker Desktop or your system. Ensure that WSL2 is enabled in Docker settings.
Issue: Unable to pull Docker images or run containers
- Solution: Verify that your WSL2 distribution is correctly set up and running by checking wsl -l -v in PowerShell.
Issue: Docker container has no internet access
- Solution: Ensure that WSL2 is properly configured for networking. Restart Docker and WSL2 to resolve network-related issues.

Conclusion

With the combination of Docker and WSL2, Windows users can now run Linux-based containers natively, enjoying the best of both worlds—Windows and Linux. WSL2 provides a lightweight, efficient way to run a Linux kernel on Windows, allowing developers to easily switch between platforms and develop applications in a containerized environment.