How to Install Docker on WSL (Windows Subsystem for Linux) – Step-by-Step Guide

Install Docker natively in WSL (Ubuntu) — Step by step

This guide shows how to install Docker **inside WSL (Ubuntu)** so Docker runs natively in your Linux distro (no Docker Desktop dependency).
Follow each step exactly — copy & paste the commands into your WSL terminal.

Prerequisites ✅

• Windows 10/11 with WSL2 enabled (recommended).
• An installed Linux distribution (Ubuntu 20.04 / 22.04 recommended) from Microsoft Store.
• Basic familiarity with terminal commands.

Quick checklist (what this post will do)

• Enable/update WSL (if needed)
• Install Docker Engine packages inside Ubuntu
• Start Docker daemon and test with hello-world
• Make Docker usable without sudo and provide troubleshooting tips

1. Make sure WSL2 is installed and your distro is set to WSL2

Open PowerShell as Administrator and run:

wsl --install         # installs WSL + default distro (Windows 11). Use only if WSL is missing.
wsl --set-default-version 2

If you already have Ubuntu, check its WSL version and convert if needed:

wsl --list --verbose
wsl --set-version Ubuntu 2

2. Update Ubuntu packages

Open your Ubuntu terminal (WSL) and run:

sudo apt-get update
sudo apt-get upgrade -y

3. Install required packages for Docker

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

4. Add Docker’s official GPG key and repository

Create keyrings directory and add Docker GPG key:

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

Add the stable repository:

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

5. Install Docker Engine & related packages

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

6. Start Docker daemon

Depending on your WSL setup you have two options:

Option A — standard service start (works if service is available)

sudo service docker start

Option B — manual daemon (if systemd/service not available)

sudo dockerd &

Leave that terminal open (dockerd prints logs). Open a new WSL tab to run CLI commands.

7. Verify installation

docker --version
docker run hello-world

You should see the “Hello from Docker!” message — this confirms the daemon and client can talk and Docker can pull images.

8. Use Docker without sudo (optional but convenient)

sudo usermod -aG docker $USER
# then close WSL and reopen it (or run: newgrp docker)

After re-login you can run docker ps without sudo.

9. Run a sample container (NGINX)

docker run -d -p 8080:80 nginx
# open in Windows browser: http://localhost:8080

WSL maps ports to Windows localhost by default — so use http://localhost:8080 from your browser.

Troubleshooting & common issues

• “Unit docker.service not found” — that means Docker packages are not installed. Re-run the install commands in step 5.
• Network / image pull errors (DNS or proxy) — if docker pull fails with DNS errors:

  sudo rm /etc/resolv.conf
  echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
  sudo chattr +i /etc/resolv.conf

  Then restart WSL (from Windows PowerShell: wsl --shutdown) and reopen WSL.

• Docker Desktop conflict — if Docker Desktop is installed and you want a pure WSL Docker, quit / uninstall Docker Desktop to avoid daemon conflicts.
• dockerd & start on boot — WSL does not always run systemd. If systemctl is unavailable, you can start dockerd in a background terminal or use an autorun script (see note below).

Auto-start Docker when WSL starts (simple approach)

WSL may not run systemd by default. A simple hack is to add a small script and run it when you open WSL (or add it to your shell profile):

# create ~/start-docker.sh
cat > ~/start-docker.sh <<'EOF'
#!/bin/bash
# start docker daemon if not running
if ! pgrep -x "dockerd" >/dev/null; then
  sudo dockerd >/tmp/dockerd.log 2>&1 & disown
fi
EOF

chmod +x ~/start-docker.sh

# then call it from ~/.bashrc or ~/.profile:
echo "~/start-docker.sh &" >> ~/.bashrc

Note: this runs dockerd in background each time you open WSL. It’s not as clean as systemd, but it works on most WSL installs.

Security notes

• Adding your user to the docker group yields convenience but has security implications — a user in the group can escalate privileges.
• Use official images and keep Docker updated: sudo apt-get update && sudo apt-get upgrade docker-ce -y

Summary

You have successfully installed Docker inside WSL Ubuntu. You can now run containers natively without Docker Desktop. Use the commands above to manage containers, pull images, and run services. If you want, I can provide a single ready-to-run install-docker.sh script that automates all steps — tell me and I’ll generate it.