How to Set Up Docker in WSL2: Complete Development Guide

Running Docker in Windows Subsystem for Linux 2 (WSL2) provides a powerful, native Linux container experience right from your Windows machine. This guide will walk you through setting up and optimizing Docker in WSL2 for seamless development.

Whether you’re new to containerization or looking to improve your development workflow, running Docker in WSL2 offers significant performance advantages over traditional Windows-based Docker installations. Let’s dive into getting everything configured properly.

Table of Contents

• Prerequisites
• Installing Docker in WSL2
• Configuring Docker to Start Automatically
• Setting Up Docker Without Sudo
• Verifying the Installation
• Optimizing Docker Performance in WSL2
  • Memory Management
  • Volume Mounting Performance
• Working with Docker Compose
• Best Practices for Docker in WSL2
• Troubleshooting Common Issues
  • Docker Daemon Not Starting
  • Permission Denied Errors
• Conclusion

Prerequisites

Before we begin, ensure you have:

• WSL2 installed and running (If not, check out our complete WSL2 installation guide)
• Windows 10 version 2004 or higher
• A Ubuntu (or preferred Linux distribution) WSL instance

Installing Docker in WSL2

Let’s start by installing Docker in your WSL2 Linux distribution. Open your WSL2 terminal and follow these steps:

Update your package index:

sudo apt-get update
Code language: JavaScript (javascript)

Install required dependencies:

sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release
Code language: JavaScript (javascript)

Add Docker’s official GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
Code language: JavaScript (javascript)

Set up the stable repository:

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Code language: PHP (php)

Install Docker Engine:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
Code language: JavaScript (javascript)

Configuring Docker to Start Automatically

By default, Docker won’t start automatically in WSL2. Let’s fix that by adding a startup script:

Create a new startup script:

sudo nano /etc/wsl.conf

Add the following content:

[boot]
command="service docker start"
Code language: JavaScript (javascript)

Setting Up Docker Without Sudo

To use Docker commands without sudo, you’ll need to add your user to the docker group:

sudo usermod -aG docker $USER
Code language: PHP (php)

Note: You’ll need to restart your WSL instance for these changes to take effect.

Verifying the Installation

Let’s verify that everything is working correctly:

docker --version
docker run hello-world

If you see the Docker version and the hello-world container runs successfully, your installation is complete!

Optimizing Docker Performance in WSL2

To get the best performance from Docker in WSL2, consider implementing these optimizations:

Memory Management

Create a .wslconfig file in your Windows home directory (%UserProfile%):

[wsl2]
memory=6GB
processors=4
swap=2GB

Adjust these values based on your system’s capabilities.

Volume Mounting Performance

When working with mounted volumes, keep your project files within the Linux filesystem for optimal performance. For example:

# Good - Files in Linux filesystem
docker run -v /home/user/project:/app node:latest

# Avoid - Files in Windows filesystem
docker run -v /mnt/c/Users/user/project:/app node:latest
Code language: PHP (php)

Working with Docker Compose

Docker Compose is essential for managing multi-container applications. Install it with:

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Code language: JavaScript (javascript)

Create a sample docker-compose.yml file:

version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./src:/usr/share/nginx/html
Code language: JavaScript (javascript)

Best Practices for Docker in WSL2

Image Management

Regularly clean unused images and containers:

docker system prune -a


1. Network Configuration

   • Use the WSL2 network bridge for container communication
   • Expose ports carefully using the -p flag

2. Volume Mounting

   • Keep project files in the Linux filesystem
   • Use bind mounts for development
   • Consider named volumes for persistent data

3. Resource Management

   • Monitor resource usage with docker stats
   • Set container resource limits when needed

Troubleshooting Common Issues

Docker Daemon Not Starting

If the Docker daemon isn’t starting automatically:

sudo service docker start

Permission Denied Errors

If you encounter permission issues:

Verify docker group membership:

groups $USER
Code language: PHP (php)

Reset the Docker daemon:

sudo service docker restart

Conclusion

You now have a fully functional Docker development environment in WSL2! This setup provides native Linux container performance while maintaining the convenience of your Windows desktop environment. As you begin working with containers, remember to keep your images updated and regularly clean up unused resources to maintain optimal performance.

Start exploring Docker’s capabilities by building your first container or deploying a multi-container application using Docker Compose. If you’re looking to enhance your development environment further, check out our guide on Creating a Complete JavaScript Development Environment in WSL2.

What container-based project will you build first with your new Docker + WSL2 setup? Share your experiences and questions in the comments below!