scroll-behavior: smooth;

Zdenek Polach

Transform any Linux Docker Image to WSL2 Distribution by PowerShell Easily


My primary job is a Windows developer. Then my workstation and laptop use Windows as primary OS. But I need to use Linux too. CD/CI systems run on Linux. My HomeLab systems run on Linux. Ansible to manage them needs Linux. The Gatsby powered my blog needs Linux too. A Linux instance is absolutely necessary for me even I’m Windows developer…

In the past I used Linux virtual machine for my Linux tasks. But when Microsoft introduced the Window Subsystem for Linux I have fallen in love with this technology. It’s lightweight, well integrated with MS Windows as well as with VS Code. Especially WSL2 version is exactly what I need for my Linux tasks.

But I’m not Debian based world man. I migrated from Ubuntu to CentOS and Fedora several years ago. I’m happy with that but for WSL world it’s a problem because these systems are not easily available for WSL. Then I have started to search solution.

If you dig deeply into the WSL2 technology then you will find that “image” exported by the wsl.exe —export is Linux filesystem packed to one tar file. Optionally it can be compressed by gzip to save space. But how and where we can get these files for any Linux distribution?

The answer is: from DockerHub by Docker!

If you deploy a Docker container on the Docker Engine:

docker pull fedora
docker create -t -i fedora bash

and then export the container by this way:

docker export --output="fedorawsl2img.tar" fedora

then the exported file is exactly what we want. Finally the exported file can be used by the WSL:

wsl.exe -–import Fedora c:\FedoraWslDisk fedorawsl2img.tar

Voila! You have Fedora based WSL2 instance up and running.

So straightforward solution is:

  • Install Docker
  • Pull the image to the Docker
  • Deploy the image as the Docker Container
  • Export the Container to WSL image
  • Import the WSL image to deploy WSL instance

Simple recipe but complicated and time consuming process, isn’t it? Especially if you don’t have Docker up and running.

Is possible to make things easier? Simplify them and automate? What if we download the Docker image directly? Can we use this for WSL?

The answer is, yes, but not straightforward. The Docker image isn’t homogenous file. It’s set of “layers” described by special manifest file. When Docker deploys an image as container then it downloads the manifest first. Based on this manifest Docker downloads all image layers and finally combine these layers to final Linux Filesystem structure. To transform the Docker image to WSL2 image without running Docker instance you have to “combine” these layers to one file yourself.

And it’s exactly what my PowerShell script download-wsl2-imgage.ps1 does. Just specify DockerHub image, image tag (alias version), destination folder where WSL2 image will be stored and, in a minute, or two, you have prepared WSL2 image of your choice…

download-wsl2-imgage.ps1 -Image library/fedora -Tag 32 -Destination C:\WslImages\Fedora

You are not limited just for fedora. What do you want? Just choose right DockerHub Image name:

  • CentOS: library/centos
  • Ubuntu: library/ubuntu
  • ArchLinux: library/archlinux

And many more! Easy, isn’t it?

Can you try it yourself? No problem, checkout my GitHub repository:

and you can download whatever you want.

IMPORTANT NOTICE Because the script run in Windows environment then is not possible to combine Docker Image layers by straightforward recipe: extract them all to one folder and then pack the folder back to final image. This throw away Linux filesystem attributes!

A workaround is necessary. Layers are tar files (compressed by gzip) and Tar files can be easily concatenated. But by tar file structure, simple merge two files together can cause improper final file format sometimes. To make concatenation by right way we must use the ‘tar –-combine’ command.

Unfortunately native tar executable included as part of Windows OS has limited functionality and combine command is not included here. Type in your console:

tar –combine

and you will get:

tar.exe: Option --combine is not supported
  List:    tar.exe -tf <archive-filename>
  Extract: tar.exe -xf <archive-filename>
  Create:  tar.exe -cf <archive-filename> [filenames...]

Due this I have to include another tar executable in my repository. The file ‘img-pkg.exe’ (renamed to avoid possible conflict with other tar executables) is here fot this purpose. Without this special binary, my script doesn’t work. I mention this to avoid worries to use unknown binary checked out from my repository. If you do not trust this version, just find your own tar executable which support the —combine option, rename it to ‘img-pkg.exe’ and you are done.

Ok then. The first important task - get any distibution up and running inside the WSL2, can be done by the download-wsl2-imgage.ps1 script.

But pure Docker image is not as rich as necessary for daily use as WSL2 instance. Some tailoring is necessary to reach final state.

If you checked out the wsl-scripts repository, you have found that contains second script: deploy-wsl2-image.ps1. By this script is possible to easily automate deployment of WSL2 images and it’s bootstrapping. Then you can get own tailored WSL2 image up and running easily.

In my next article I will provide more info about that. So stay tuned 😉

© Zdenek Polach - Last update 21.12.2020 18:02.