How to Install Docker in WSL2 Without Docker Desktop

You can install Docker in WSL2 with a few apt commands, no Docker Desktop required. Add Docker’s official repository inside your Ubuntu distro, install docker-ce, add yourself to the docker group, and you’re running containers. Below are the exact commands, plus how to start Docker automatically, use it without sudo, and fix the errors that come up most.

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!