Using Windows Subsystem for Linux (WSL), we have a choice of Linux distributions available in the Windows Store, such as Ubuntu, Kali, Debian, etc.
In addition to these, with WSL 2, installing custom distributions is fairly straightforward, even if they are not in the Windows Store:
- find a rootfs for the distro
- install with
wsl --importin Windows Powershell or Command Prompt
Lately I rely on Fedora in WSL 2, and have been thoroughly pleased with that distro. Here are the steps I used to get up and running with Fedora on WSL.
Already have Fedora 33 on WSL 2, and just want to upgrade to Fedora 34? I documented the steps involved in another article; feel free to take a look.
Please note that these steps require WSL 2 (not version 1).
Does the command
wsl --set-default-version 2 work? This will set the default version to WSL 2, or fail if you are still on the first version.
To run WSL 2, Windows version 1903 or higher is needed, with Build 18362 or higher. To tell what version you are running, run
winver in Powershell or CMD, or just type Win key and R (⊞-r) to open the Run dialog and then enter
winver. Hopefully you will see something like "Version 2004. OS Build 19041.329"
We first need a rootfs (the base filesystem for the Linux distro in question, in this case Fedora). There a few ways to get this.
The rootfs embedded in the Fedora Container Base project seems to work well, and is my preferred method, as it offers a lot of flexibility. I start with the most recent stable version of Fedora that auto-built successfully. If you want to be bleeding edge, you can download the latest Rawhide image that built successfully, but I am using the latest Fedora 34 for now. The "State" column indicates build success. Pick the latest with a green checkmark.
Find the right "xz" file for your platform (likely
x86_64). Such as this one for the April 18, 2021 build of Fedora 34. Note that Fedora 34 is still in beta, with a hoped-for release at the end of April. Of course, if you are still wanting Fedora 33, this Fedora 33 build from April 18 should work.
Fedora-Container-Base-*.tar.xz file in your preferred manner. You might try 7-zip for this, extracting the .tar file, then extracting the contents of the .tar file. This, however, is not your rootfs. Further work is needed.
Once unpacked you will see a folder with a long hexadecimal name. Within that folder, there should be a
layer.tar file. This is your rootfs. Copy the
layer.tar file to a logical location, such as your Downloads folder. You may even want to rename it to something like
The docker-brew-fedora project imports "the official Fedora Docker Base Images built in Fedora Koji (Fedora's Build System) so that they may be submitted to the official-images repository for the Docker Hub."
To download, first pick your desired Fedora version from the active branches. For example, you might choose Fedora 34 and there find a file with a name like
fedora-34.20210329-x86_64.tar.xz. Or go for Fedora 33 already and locate
fedora-33.20210401-x86_64.tar.xz. Download that file.
fedora-3?.*-x86_64.tar.xz file in your preferred manner. You might try 7-zip for this, extracting the .tar file, then, if desired, renaming it to something like
While this requires an extra tool, if you already have docker or podman available, then you can pull the Fedora image of your choosing and export the rootfs. In the following, if you have a Linux distro with podman available, you can substitute
podman in place of
docker run --name fedora34 fedora:34 docker export -o fedora-34-rootfs.tar fedora34
First we create the container, name it "fedora34", then export the rootfs as "fedora-34-rootfs.tar". Afterward, you can certainly
docker rm fedora34 to clean up.
Once we have the rootfs, we can prepare to import it.
I like to use
wsl in my home directory, so in this case I create that folder and a
fedora folder within it. In Powershell, that's:
In Powershell, assuming you want to name the distro "fedora" and the folder is \$HOME\wsl\fedora and the rootfs is in Downloads, named "fedora-34-rootfs.tar":
wsl --import fedora $HOME\wsl\fedora $HOME\Downloads\fedora-34-rootfs.tar
If this is the only WSL distro you now have, executing
wsl -l should look something like this:
PS C:\Users\me> wsl -l Windows Subsystem for Linux Distributions: fedora (Default)
wsl -d fedora
Or, if Fedora is the default, simply
wsl should result in a BASH prompt.
If you have multiple distros installed, and want Fedora to be set as the default, something like this should work:
wsl -s fedora
DNS in WSL is interesting. By default, WSL will set the DNS server automatically, dynamically configuring
/etc/resolv.conf. If your dns is resolving fine (does
sudo dnf upgrade work for you?) then you can skip to the next section.
For me, however, the dynamic
/etc/resolv.conf has not worked consistently. I need to turn it off and configure
Conveniently, WSL provides a means in
/etc/wsl.conf to set some configuration settings specific to WSL.
In order for DNS to work, we will create our own resolv.conf, but first we create a new wsl.conf file and disable auto-generation of resolv.conf:
echo -e "[network]\ngenerateResolvConf = false" > /etc/wsl.conf
Now exit WSL, then terminate it with
wsl -t fedora
Then enter it again with
wsl -d fedora
Now we can persist our custom DNS configuration. First,
unlink /etc/resolv.conf. This covers cases in which
/etc/resolv.conf is linked to systemd-resolved or resolvconf generated files. Then create a new
/etc/resolv.conf with the nameserver(s) of your choice:
unlink /etc/resolv.conf echo nameserver 188.8.131.52 > /etc/resolv.conf
Why not test network settings now with a system upgrade:
If repositories are synced, you have success!
root should never be your default user. Let's create a normal user.
We are going to need
passwd for this, and we might as well get the cracklib dicts for password checking, too. Install both, once you have launched Fedora:
dnf install -y passwd cracklib-dicts
Now, create a new user; while we are at it, let's add them to the
wheel group so the user can
sudo (don't forget to replace "myusername" with something that makes sense for you):
useradd -G wheel myusername
Then create a password for that user:
Now, exit WSL or launch a new Powershell window, then re-launch WSL with the new username:
wsl -d fedora -u myusername
$ whoami myusername
sudo cat /etc/shadow
If you see the list of users, including, toward the bottom, the one you recently added, then all is well!
In Fedora, the user you created likely has a user id of 1000, but you can check with
id -u. Remember that number.
Back in Powershell you can set the default user by editing the Windows registry, changing "fedora" and "1000" to what you named your WSL distro and the user id, respectively:
Get-ItemProperty Registry::HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\*\ DistributionName | Where-Object -Property DistributionName -eq fedora | Set-ItemProperty -Name DefaultUid -Value 1000
Launch WSL again, without specifying a user, and you should be that user, not root.
A newer way of doing this, if you have Windows build 18980 or later: simply add a user section to
If you do container work, especially in userspace, you will likely want to reinstall shadow-utils, in order to fix sticky bits that weren't set properly in the rootfs:
sudo dnf reinstall shadow-utils
If you like to ping servers to see if they are up, then these two steps may be necessary:
sudo dnf install procps-ng iputils sudo sysctl -w net.ipv4.ping_group_range="0 2000"
The second one allows group IDs all the through 2000 to be able to ping. You can check group IDs with
getent group or see your primary group ID with
id -g and make sure it is included in the range above.
You may also find other commands you are used to are missing from the sparse rootfs we installed. You may want to install
ncurses, and others, like so:
sudo dnf install iproute findutils ncurses
From here, you can proceed to install packages, edit configurations, and customize your new distro to your heart's content!
Once you have a pristine base system the way you want it, why not export a tarball that you can import later. I mean, I am honored if you want to read this article again and follow it step by step. But if you want life to be a little easier, you might try this the following.
First, clean up downloaded packages, etc. within Fedora:
sudo dnf clean all
Then, exit WSL and export the whole installation to a tarball:
wsl --export fedora $HOME\Downloads\fedora-wsl.tar
You may want a different folder than
Downloads; specify the location you desire.
Depending on what packages you installed, it may be as small as a quarter GB. You could gzip it if you want the storage size to be even smaller. Next time you want to start fresh, you can do something like this:
mkdir $HOME\wsl\freshfedora wsl --import freshfedora $HOME\wsl\freshfedora $HOME\Downloads\fedora-wsl.tar
Even if you have a prerelease, there should be no need to reinstall. Just keep upgrading; the process is pretty seamless:
sudo dnf upgrade
For instance, if you decided to use Fedora 35 (you adventurer, you!), upgrade as often as you like with the above command, and you will eventually (by November of 2021, presumably) be at release.
Other articles I have written on WSL: