WSL+Docker: custom distro 2.0

Jan 29 · 5 min read


Sometimes, crazy ideas can get simplified and become even more crazier.

A little bit more than 1 year ago, Monsieur Brian blogged about repeatable WSL environment in order to keep his development environments isolated while still applying some (light) templating.

While the solution really worked fine, it requested a third party (LxRunOffline) software to make the separation between the different environments based on a same distro (i.e. ubuntu).

Fast forward to the Windows 10 Insiders version 18305 and we finally have a wsl.exe on steroids and can reproduce Brian’s example in a “compliant and validated” way! (I swear, no Dance with Dragons this time, Rich!)

Important note: store distros are “more”

This tutorial will show a “new” way of creating a custom WSL distro, however the distros in the Microsoft store (free or paid) are bundled expressively for WSL with added tools and optimizations.

So I do recommend strongly, for production purpose, you still use the store distros.
Bonus: you will get support by the vendor/creator (i.e. Suse Enterprise, WLinux Enterprise)!


As stated above (and in the title) we will need 2 specific components:

  1. Windows 10 Insider preview version 18305 (minimum)
  2. Docker for Windows

Nowadays, Linux Containers on Windows (LCoW) is getting very near to an “ on-par” state compared to the Linux Containers on the Moby VM.
This means that you can choose either “mode”, there should be no differences (at least for what we will be doing with).

The most important task: pick a distro

And yes, already at the critical point of this blog: we now need to pick a “new” distro to add to our, ever-growing, WSL distros.

I know, it might sound impossible, but believe me: You can do it!

Ok, bad joke about choices, but to be totally sincere I didn’t know which one to pick for this post.
I decided to go with archlinux for 2 main reasons: originality and request from the community.

Having an archlinux based WSL distro might be one of the most common requests I see in the WSL github issues/requests. And thanks to the unique aspect of archlinux it will also serve a good educational purpose of getting a distro ready (almost) “from scratch”.

Finally, while the image is not (yet) an official image in Docker Hub, it has more that 1 Million downloads. So it “validates” in a sense that the image is not corrupt.
But yeah, a nice “Official image” tag would make things more trustful (à la Alpine):

The Alpine image is tagged as “Official”
While the Archlinux image is not…

Enough talking, let’s do it.

At the beginning there was the image

As you’ve guessed it by now, the first step will be to save the docker image.
To perform this task, we have 2 possibilities:

  1. docker save will allow us to save the image without the need to create a container instance.
    This is very useful if we don’t want to change anything from the image created by the owner/vendor.
  2. docker container export will allow us to save a container instance.
    This is very useful if we want to save a container instance where we did apply some config changes.

In our example, we will take the option 2, as we will prepare our distro in the container instance, before migrating it to a WSL distro.

Distro customization

For the ones who created a custom distro using the Microsoft example project, you will find the steps below very familiar:

### Create a container instance from the Archlinux image
docker run -it --name archlinux base/archlinux
### Update the system
pacman -Syu
### Create your user (avoids using root) and assign a password
useradd -m <username>
passwd <username>
### Install sudo and vim (or any other editor)
packman -S sudo vim
### Set vim (or your editor) as default and edit the sudoers file
export EDITOR=/usr/bin/vim
<username> ALL=(ALL) NOPASSWD: ALL
### Create /etc/shadow and /etc/gshadow
### Make /etc/shadow and /etc/gshadow writeable
chmod 0744 /etc/shadow
chmod 0744 /etc/gshadow
### Delete /etc/resolv.conf to allow WSL to generate a version based on Windows networking information
rm /etc/resolv.conf
Creation of the container up and update of the system

From container to a p̶o̶k̶e̶b̶a̶l̶l̶ tarball

Once the (basic) customization is done, we can save the container instance into a .tar file as it’s the format that wsl.exe import will require:

### Exit the running container (if not already the case)
### Save the container instance to a .tar file (the container name, set during its creation, will be used)
docker export --output=install.tar archlinux
### Check that the .tar file has been correctly created
dir .\install.tar
Creation of the .tar file from the Container instance

Rise of the distro

Now that we gathered all the components, we will finally be able import the .tar file into WSL and create a new distro:

### Create a new directory to store all the distros
mkdir c:\wsldistros
### Copy the .tar file into the distros directory (for a better management, I will rename the .tar file to the distro name)
cp .\install.tar c:\wsldistros\archlinux-install.tar
### Go to distros directory and create the new distro
cd c:\wsldistros
wsl.exe --import wslarch .\wslarch .\archlinux-install.tar
### Check that the distro has been correctly created
wsl.exe --list
### Run the newly created distro with the user created during the customization
wsl.exe -d wslarch --user <username>
Creation of the new distro completed

From one to many

Thanks to the .tar file and the wsl.exe import function, we can now “multiply” our instances as Brian did using lxrunoffline:

New distro created from the same .tar file and fully isolated


In this post, I showed the (very) long way on how to have a distro template created from a container instance.

But for the ones knowing (even a bit) of Docker, there is a short/fastest way to get to the same result without all the typing inside the container: dockerfile

I will add some bonuses in the future (thanks Taylor for an initial crazy idea), and, as usual, I’m just curious to know what you will do with this trick, so do not hesitate to contact me on Twitter.


Written by


WSL Corsair + Winsider + Docker fanboy and Cornerstone Client Advocate.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade