Prerequisites

Before following this guide, you should have Windows configured with WSL2 enabled, Ubuntu installed and VS Code installed as detailed in the Setting Up a Windows Development Environment guide.

Choosing a Method for Running Docker

Before we get into the details of how to set up Docker for development, you will need to make a choice about how to run it with your WSL2/Ubuntu setup:

Option 1: Docker Desktop with WSL2 Integration

With this approach, you install Docker Desktop on Windows and configure it to use WSL2 as the backend, integrating with your Ubuntu distro to run containers.

Pros

• Ease of Use: Docker Desktop’s GUI lets you monitor containers and manage settings within Windows, while the Docker CLI works seamlessly in WSL2’s Ubuntu terminal.

• VS Code Integration: It pairs perfectly with VS Code’s Remote - WSL extension, allowing container management from your WSL2 workspace.

• Unified Daemon: The Docker daemon runs on Windows and is shared with WSL2, simplifying setup and resource use.

Cons

• Windows Dependency: Relies on a Windows application, which might feel less native for WSL2-centric workflows.

• Resource Overhead: Docker Desktop runs a background process on Windows, using slightly more resources than a WSL2-only daemon.

Option 2: Docker Directly in WSL2

Here, you install the Docker daemon and CLI entirely within your WSL2 Ubuntu distro without the need to install Docker Desktop.

Pros

• Lightweight: No Windows overhead—just a Docker daemon running in WSL2’s VM.

• Full Control: Managed entirely within Ubuntu, offering a pure Linux experience.

• No Licensing Cost: Uses the open-source Docker engine so no need for a license (at time of writing).

Cons

• No GUI: Lacks Docker Desktop’s graphical interface for monitoring and management.

• VS Code Complexity: The "Docker" extension may need extra configuration to connect to the WSL2 daemon, potentially causing hiccups.

• Networking Challenges: Exposing container ports to Windows or other machines can be trickier without Docker Desktop’s built-in support.

Option 3: Docker, or another container engine, on a remote machine

There are many possible configuration here so I won't cover them in this guide but if you already use a remote machine for containerized development, you can make use of Visual Studio Code's Remote - SSH extension to connect and use that.

Which Should You Choose?

Choose Docker Desktop with WSL2 if:

• You want a balance of performance, ease of use, and VS Code integration.

• You’re okay with a Windows dependency and its licensing terms.

• You value the GUI for managing containers alongside CLI flexibility in WSL2.

Choose Docker in WSL2 if:

• You prefer a lightweight, fully Linux-native setup.

• Licensing restricts Docker Desktop use for your organization.

• You’re comfortable managing Docker manually and don’t need a GUI.

Recommendation

If you are still unsure I would make the choice purely on the Docker Desktop licensing. Read through the licensing and pricing documents:

• https://www.docker.com/pricing/

• https://www.docker.com/legal/docker-subscription-service-agreement/

• https://www.docker.com/pricing/faq/

At the time of writing this, if you will be using it purely for personal use, or working for a small company (< 250 employees), you may be able to use the free version of Docker Desktop but do check restrictions. Otherwise you will need to purchase a license if you don't have one already. If any doubt, just follow the instructions to install the free version of the Docker engine (not Docker Desktop) in WSL2.

Setting Up and Integrating Docker Desktop (Option 1)

Please ensure you have first read the previous section to decide whether this is the best approach for you.

Install the Main Docker Desktop Application on Windows

1. Download Docker Desktop for Windows from https://www.docker.com/products/docker-desktop/.
2. Run the installer. During setup, ensure "Install WSL 2 backend" is checked (Docker Desktop will prompt to enable WSL2 if not already enabled).
3. After installation, launch Docker Desktop. It’ll ask to integrate with WSL2—accept this.
4. In Docker Desktop settings:
   • Go to "Settings > Resources > WSL Integration."
   • Enable integration with your Ubuntu distro (e.g., Ubuntu-22.04).
   • Apply changes.

Install Docker CLI in WSL2

Docker Desktop provides the Docker daemon, but you need the CLI in WSL2 to run commands.

1. In your Ubuntu terminal (WSL2), install the Docker CLI:

$ sudo apt update
$ sudo apt install docker.io -y

2. Add your user to the docker group to run Docker without sudo:

$ sudo usermod -aG docker $USER

3. You'll need to log out and back into WSL2 for the group change to take effect, I recommend shutting down the WSL2 session and restarting the terminal to make sure it's applied to all your future sessions.

$ wsl --shutdown

Verify Docker Works in WSL2

1. In your WSL2 terminal, test Docker:

$ docker run hello-world

This pulls a small test image and runs it. If it works, Docker is set up correctly.

2. Verify Docker Compose is installed (included with Docker Desktop):

$ docker-compose --version

Working with VS Code

1. Open your WSL2 workspace in VS Code:

   code .

2. Install the "Docker" extension in the WSL2 context (Extensions view > install in WSL).

3. Use the extension’s sidebar to manage containers, or run CLI commands in the integrated terminal.

---

Installing and Using Free Docker in WSL2 (Option 2)

Please ensure you have first read the first page on choosing a method for running Docker to decide whether this is the best approach for you.

This guide explains how to install and use the free, open-source Docker engine directly in Windows Subsystem for Linux 2 (WSL2).

Step-by-Step Installation

1. Ensure gnupg, curl and ca-certificates are installed

sudo apt install -y gnupg curl ca-certificates

You may have all of these already installed at this stage, but it doesn't hurt to check.

2. Configure the Docker repository

$ sudo install -m 0755 -d /etc/apt/keyrings

$ sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

$ sudo chmod a+r /etc/apt/keyrings/docker.asc

$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

$ sudo apt-get update

A GPG key is a digital signature that ensures the packages you download are authentic. When you install packages using the "apt" package manager keys are used to verify the packages that are downloaded. The commands above adds the official Docker GPG key to your system by:

• Creating a "keyrings" directory in the correct place to store the key.
• Downloading the Docker GPG key into the directory.
• Setting the correct permissions on the key.
• Adding the Docker repository to the package sources list.

Now we can install the Docker packages in the same way we have been installing other packages with apt, so let's do that.

3. Install the Docker packages

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

The components we've installed are:

• docker-ce: The Docker engine and daemon (CE stands for Community Edition).
• docker-ce-cli: The command-line tools to control Docker.
• containerd.io: The underlying container runtime (handles container execution, image management, and storage).
• docker-compose-plugin: Native support for multi-container apps, for example running a React app in one container with a database in another.

6. Start the Docker Daemon

Start the Docker service manually

$ sudo service docker start

7. Allow Non-Root Access

Add your user to the docker group to run Docker commands without sudo.

$ sudo usermod -aG docker $USER

This won't take effect until you log out and back into your WSL2 session however it's handy to make the change now to make things easier later. For now we'll just run the command with sudo.

8. Verify Installation

Test that Docker is working by running a simple container.

$ sudo docker run hello-world

If successful, you’ll see a welcome message from the hello-world container.

9. Persisting the Daemon

Whenever you restart your WSL2 session or your machine, you'll need to start the Docker daemon again unless it's enabled for startup. The easiest way to do this is through a service manager called systemd, if you have a linux background you may already be familiar with it. systemd allows you to enable and disable services to start and stop at boot (in the case of WSL2, when the session initializes) and at shutdown.

Historically, systemd was not enabled by default in WSL2, so first lets check that it is, in your Ubuntu/bash terminal run:

$ ps aux | grep systemd

If you see a number of processes that include "systemd" then it's enabled, if not (or unsure), you can ensure it's enabled by editing the /etc/wsl.conf file. Type:

$ sudo nano /etc/wsl.conf

And add these lines:

[boot]
systemd=true

Now, save the file and quit (Ctrl+X, Y, Enter).

You'll need to restart your WSL2 session for the changes to take effect, you can do this by running:

$ wsl --shutdown

And start a new Ubuntu/bash session.

You can start and enable the Docker service by running:

$ sudo systemctl enable docker
$ sudo service docker start

You shouldn't now need to start the Docker service manually each time you restart your WSL2 session or machine.

Working with VS Code

1. Open your WSL2 workspace in VS Code:

   code .

2. Install the "Docker" extension in the WSL2 context (Extensions view > install in WSL).

3. Use the extension’s sidebar to manage containers, or run CLI commands in the integrated terminal.