Running Linux containers on Windows Home with WSL2

I have two computers that I use for software development, in part for writing applications that run in Docker containers. My primary machine runs Windows 10 Pro and it’s where I do the bulk of my coding. I also like to use my laptop to get away from my desk from time to time. But that machine runs Windows 10 Home, which until recently, couldn’t run Docker without some workarounds. That’s now a thing of the past with the release of WSL2.

WSL1 vs WSL2

WSL1 made my daily work easier. For starters, it meant I could easily SSH into Unix-based machines and test any bash scripts that I wrote on my local machine. WSL2 opens up even more possibilities by actually running a Linux kernel under the hood. Microsoft and Docker worked together to enable Docker Desktop to run in the WSL VM, eliminating the need for Hyper-V, and therefore bringing Windows Home into the picture.

Below are the steps I followed to get my Windows Home machine running Docker under WSL2. It was all fairly straightforward, but there were a few gotchas here and there.

Prerequisities

There are two requirements to get Docker running on Windows Home. The first is to be on Windows version 2004 or greater. You can find the version you’re running by typing winver at the command prompt. You may have already gotten the update automatically, but if you haven’t, Windows Update should offer it to you as an optional install. Alternatively, you can use the Update Assistant Tool to install it if Windows Update doesn’t offer you the option.

The second requirement is to install WSL1. That’s done through the Windows Features menu:

With that done, you can install any Linux distro offered on the Microsoft Store. I use Debian since it’s what the ASP.NET Core Docker image is based on, but it can be any distro of your choice.

Configuring WSL2

Next, it’s time to enable WSL2 with the following PowerShell command:

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

Then, it’s time to update my existing Debian Linux distro to WSL2:

wsl --set-version Debian 2

I also set the default for any other distros installed from here on out to use WSL2:

wsl --set-default-version 2

Finally, I set the default distro to be used by WSL. This setting is used by Docker, as we’ll see in the next section:

wsl --set-default Debian

Configuring Docker

Download the latest stable Docker Desktop (2.3.0.2 or later) and double-click to install. Enable WSL2 Windows Features should already be checked on the second screen of the installer.

Once the installation is completed and Docker has started, head over to Settings -> Resources -> WSL Integration to ensure that the default WSL distro checkbox is checked, and enable any other distros you’d like to use with Docker.

Finally, I don’t think this is strictly needed, but I updated to the latest Visual Studio, 16.6 as of the time of writing this.

Then, open a project with a Dockerized application, and choose Docker as the run target. The application should start running in WSL when you start it. You can validate that’s the case by opening a shell to your Linux distro and typing docker ps.

Get Coding

WSL2 makes it possible to run Docker containers on Windows 10 Home. All that’s needed is the latest Windows, WSL2, and Docker Desktop versions. It’s allowed me to move away from Windows Pro machine without having to sacrifice on what I can work on. But more importantly, it also opens up the world of Docker to a set of developers who may have been running Windows Home.