6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
Menu
Ceos3c
Complicated Things – Made Easy
How to Set Up Docker in WSL2: Complete
Development Guide
January 25, 2025 by Naomi Brooks
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.
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
1/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
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:
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
2/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
sudo apt-get update
Install required dependencies:
sudo apt-get install -y \
apt-transport-https \
ca-certificates \
curl \
gnupg \
lsb-release
Add Docker’s official GPG key:
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share


Set up the stable repository:
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://


Install Docker Engine:
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
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:
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
3/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
[boot]
command="service docker start"
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
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.
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
4/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
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
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-compos
sudo chmod +x /usr/local/bin/docker-compose


Create a sample docker-compose.yml file:
version: '3.8'
services:
web:
image: nginx:alpine
ports:
- "8080:80"
volumes:
- ./src:/usr/share/nginx/html
Best Practices for Docker in WSL2
Image Management
Regularly clean unused images and containers:
docker system prune -a
1. Network Configuration
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
5/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
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
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
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
6/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
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!
Author
Naomi Brooks
Naomi Brooks is a self-taught web developer and Linux expert with over a decade’s experience in
developing innovative web solutions. A Detroit native, she is renowned for her unique approach to
technology, breaking barriers as a black woman in tech, and is now sharing her extensive knowledge
with the ceos3c.com community.
Linux, WSL2
Web Application Security Testing Guide: Essential Tools & Techniques
TypeScript Keyof Operator: Complete Guide to Type-Safe Object Keys
Leave a Comment
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
7/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
Name *
Email *
Website
Post Comment
This site uses Akismet to reduce spam. Learn how your comment data is processed.
- Free Email Series -
🚀 Tips & Tricks directly to your Inbox
Your email address
Get Tips & Tricks
We take your privacy seriously. Read our Privacy Policy.
🔒 No spam. Unsubscribe any time.
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
8/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
Security
WSL 2
Python
JavaScript
WebDev
Linux
pfSense
SysAdmin
Reviews
Privacy Policy
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
9/10
6/3/25, 8:42 AM
How to Set Up Docker in WSL2: Complete Development Guide
Impressum (Germany)
Ethical Hacking Disclaimer
© 2025 Ceos3c • Built with GeneratePress
https://www.ceos3c.com/linux/how-to-set-up-docker-in-wsl2-complete-development-guide/
10/10