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 --import
in Windows Powershell or Command Prompt
Lately I rely on Fedora in WSL 2, and have been thoroughly pleased with that distribution. This article details the steps I use to get up and running with Fedora on WSL. By the way, if you prefer a nice out-of-box experience, take a look at the fine work by Whitewater Foundry with their Fedora Remix for WSL. But if you see "some assembly required" as an enticing invitation, read on.
Already have a previous version of Fedora on WSL 2, and just want to upgrade to the latest? I documented the steps involved in another article; feel free to take a look.
Prerequisite: WSL 2
Please note that these steps require WSL 2 (not version 1).
To run WSL 2, Windows version 1903 or higher is needed, with Build 18362 or higher. Most likely, you have a much later version than this already. 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 enterwinver
. Hopefully you will see something like "Version 21H2. OS Build 19044.1503". If on Windows 11, you needn't worry at all anyway, but the version should be something like "Version 21H2. OS Build 22000.1165".
To check if you are running WSL 2, try this command:
wsl --set-default-version 2
This will set the default version to WSL 2, or fail if you are still on the first version.
If it does neither and instead offers installation instructions, this may be your first time using WSL on this system.
Microsoft offers helpful installation instructions, including step-by-step instructions on how to upgrade to WSL 2.
In short, if you are comfortable installing another Linux distribution, running wsl --install
will install the default latest Ubuntu, or you can pick from a list by using wsl -l -o
then installing one with wsl --install -d Debian
or, if not Debian, whichever distribution you would like.
If you are on an older version of Windows 10 or using WSL version 1, then the following Powershell command should get you to where you need (a reboot will likely be necessary).
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux,VirtualMachinePlatform -All
Most likely, the wsl
command will then instruct you to install a new kernel, so proceed to https://aka.ms/wsl2kernel and follow the instructions there.
Again, see Microsoft's instructions for a current and detailed version.
Obtain a rootfs image of Fedora
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.
Obtain rootfs from Fedora Container Base
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 37 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:
- Fedora 37, built on October 29, 2022.
- Fedora 36, built on October 29, 2022.
- Fedora 35 built on October 29, 2022.
Unpack the 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 fedora-33-rootfs.tar
.
Alternative: download rootfs from docker-brew-fedora project
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 37 and there find a file with a name like fedora-37-x86_64.tar.xz
. Or use Fedora 36 and look for fedora-36-x86_64.tar.xz
. Or go for Fedora 35 and locate fedora-35-x86_64.tar.xz
. Download that file.
Unpack the 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 fedora-36-rootfs.tar
.
Another rootfs alternative: use docker or podman and export
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
.
docker run --name fedora37 fedora:37
docker export -o fedora-37-rootfs.tar fedora37
First we create the container, name it "fedora37", then export the rootfs as "fedora-37-rootfs.tar". Afterward, you can certainly docker rm fedora37
to clean up.
You may be interested in my articles for configuring podman on WSL, or setting up Docker on WSL.
Make a folder for your WSL distro.
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:
mkdir $HOME\wsl\fedora
Install a new WSL Fedora distro
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-37-rootfs.tar":
wsl --import fedora $HOME\wsl\fedora $HOME\Downloads\fedora-37-rootfs.tar
View installed distros
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)
Launch Fedora as root
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
Ensure DNS is functioning (skip this section if network functionality is good)
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. It seems that it just works for most people.
For me, however, the dynamic /etc/resolv.conf
has not worked consistently. I need to turn it off and configure resolv.conf
manually.
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 1.1.1.1 > /etc/resolv.conf
Why not test network settings now with a system upgrade:
dnf upgrade
If repositories are synced, you have success!
Missing the mount
command?
If, at first entry to your new Fedora instance, you are greeted with An error occurred mounting one of your file systems
, then that is a sign you are missing the util-linux
package, which includes mount
as well as other essential commands. Depending on the rootfs you installed, you may not receive any error, in which case you can proceed to the next section.
But if you do need mount, install util-linux
(or, if you are going minimalist, just install util-linux-core
).
dnf install -y util-linux
Then exit, and terminate your fedora instance (this, in effect, causes a restart):
wsl -t fedora
Launch Fedora as an unprivileged user
Just sayin': 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:
passwd myusername
Now, exit WSL or launch a new Powershell window, then re-launch WSL with the new username:
wsl -d fedora -u myusername
Success?
$ whoami
myusername
Does sudo
work?
sudo cat /etc/shadow
If you see the list of users, including, toward the bottom, the one you recently added, then all is well!
Set the default user
It would be nice to enter your Fedora instance as the user you just created, rather than as root.
To enable this, assuming you have Windows build 18980 or later: simply add a user section to /etc/wsl.conf
.
Something like this will work well if you do not already have that file, or a [user]
section in it:
printf "\n[user]\ndefault = myusername\n" | sudo tee -a /etc/wsl.conf
Then exit, and terminate your fedora instance, so that it starts fresh next time.
wsl -t fedora
Launch WSL again, without specifying a user, and you should be that user, not root.
If that succeeded, then proceed to the next section.
But if on a version of Windows before build 18980, then you will instead need to edit the registry to set a default user.
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
Fine tuning
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 -y shadow-utils
If you like to ping servers to see if they are up, then these two steps may be necessary:
sudo dnf install -y 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.
To make the above permanent, however, it is necessary to create or alter the $HOME\.wslconfig
file in Windows, not Linux. Placing the following in that file will allow ping to work even after restarts:
[wsl2]
kernelCommandLine = sysctl.net.ipv4.ping_group_range=\"0 2000\"
You may also find other commands you are used to are missing from the sparse rootfs we installed. You may want to install iproute
, findutils
, ncurses
, and others, like so:
sudo dnf -y install iproute findutils ncurses
While the included vi
is a useful text editor, you will likely want one that is either more robust or has a user interface that suits you. Good options include vim
, micro
, or nano
. Pick one and install it with something like:
sudo dnf install -y micro
From here, you can proceed to install packages, edit configurations, and customize your new distro to your heart's content!
A few good man pages
You want the docs? You can't handle the docs!
But if you can handle them, and can handle the extra storage space they will occupy, then you likely want man pages. Thanks to Martin Hinze for his good suggestions on how best to add man page functionality. This is an enhancement, rather than baked in, because we obtained a slimmed-down rootfs earlier.
First, ensure the nodocs option is not set in /etc/dnf/dnf.conf
. You may edit out the tsflags=nodocs
line yourself, or use the following:
grep -v nodocs /etc/dnf/dnf.conf | sudo tee /etc/dnf/dnf.conf
Then install man
and man-pages
:
sudo dnf install -y man man-pages
This will ensure you get man pages on every future dnf install
; however, to add them in retroactively, you will want to dnf reinstall
any package for which you want man pages. For instance, man dnf
will yield nothing now. But try it again after sudo dnf reinstall -y dnf
and you should have good results.
To reinstall all installed packages, try the following:
for pkg in $(dnf repoquery --installed --qf "%{name}"); do sudo dnf reinstall -qy $pkg; done
Don't repeat yourself
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 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
Keep upgrading
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 37 (you adventurer, you!), upgrade as often as you like with the above command, and you will eventually (by November of 2022, presumably) be at release.
Interested in further tinkering with WSL 2?
Other articles I have written on WSL:
Top comments (113)
How can we quickly create a new instance of our WSL Fedora linux? Jonathan suggests saving our customized installation by exporting it, so we can import it to get a new and clean system. This works fine. However, I would like to present an alternative: I wrote a bash script, that does the steps described above and keep it in my gitlab.com account. So I can download a new and blank container version of Fedora, launch it and run
(This script adds a non-root user, adds some basic dnf packages and man pages.)
I prefer this because I start with the current release and don't need to upgrade an older container.
Warning: Always be careful when running code from unofficial sources. :-)
I love this, @martinhinze ! Way to automate.
I just realized @trens wrote a similar script earlier.
To be able to setup the locale within fedora you need systemd. To get around this you can use the following (substitute en, en_US with your locale strings):
Additionally, you may want to install your locale resources, sucha as:
And don´t forget to check and change if necessary /etc/locale.conf and /etc/locales.conf
Thanks for these tips! OK if I incorporate them into the article?
Sure. Go ahead! Notice that I've edited the tip to add a last step.
Tried to install first non-US locale and then en_US (en) locale - now it's ignore file /etc/locale.conf and always set en_US.UTF-8
Also command
export LANG=ru_RU.UTF-8
only affects to "locale -a" command and non-localize any other packages.
Ok so I managed to use CentOS Stream in lue of Fedora.
My primary reason for the switch honestly has alot to do with Fedora's release cycle.... Fedora moves rather swiftly (give or take, A new Fedora every 6-9 months) and CentOS Stream moves slower(every 5 years). For something that is going to be on my window partition, CentOS makes alot more sense for me.
I ended up using the rootfs method. For those that care, the best way to go about that is to click on cloud install on CentOS which will bring you to this directory, and then grabbed the
file while follow the rest of the instructions.
Just thought that I mention it if you care....
I love this! Choosing CentOS Stream makes perfect sense. Thanks for the links to the rootfs!
Hello again....
Well, I can't say that the CentOS community doesn't do work. I was poking around the Project when I noticed something.
So this happened.... Yeah... everything that I did last year to get it running, forget it. The community just built a set of WSL images for CentOS Stream 9, and that page is a rather easy set of instructions to do it with.
Enjoy.
This is great news! Thank you.
i don't know if this is helpful but i was bored so i made a script to run through the steps quickly. its not that good i know, but i was bored. worked for me.
Great automation!
Thank you Jonathan! This article is top notch, it helped me out so much!
I've been in a MacOS and Linux world for about 10 years now. Just made the switch to a Windows11 desktop as my daily driver thanks to wsl2. That integration has been fantastic and being able to use my distro of choice fedora makes it all the better. Thanks again! Bob
PS, finding out about Micro editor is a cherry to top things off!
Thank you for the detailed instruction!
I have installed fedora and the distribution is running. But for some reason, the standard commands are not available:
[haosmos@Haosmos-PC haosmos]$ cd ~/
[haosmos@Haosmos-PC ~]$ nano .bashrc
-bash: nano: command not found
[haosmos@Haosmos-PC ~]$ find find .bashrc
-bash: find: command not found
[haosmos@Haosmos-PC ~]$ clear
-bash: clear: command not found
When trying to download and install any program or utility, the same error is always displayed:
The downloaded packages were saved in cache until the next successful transaction.
You can remove cached packages by executing 'dnf clean packages'.
Error: Error downloading packages:
Curl error (6): Couldn't resolve host name for https://mirrors.fedoraproject.org/metalink?repo=fedora-33&arch=x86_64 [Could not resolve host: mirrors.fedoraproject.org].
How do I fix these problems?
@haosmos , you were right and I was wrong!
Apparently, Fedora 33 uses systemd-resolvd, and when we upgrade packages with
dnf upgrade
something was overwriting/etc/resolv.conf
with a link to/run/systemd/resolve/stub-resolv.conf
which didn't actually exist.So, I updated the instructions to include a workaround for Fedora 33. Please let me know if it works!
I also added a tip at the end to install
findutils
andncurses
. Let me know if you think other basic packages should be included. Thanks!I am curious: what does your
/etc/resolv.conf
look like?Here is mine:
cat: /etc/resolv.conf: No such file or directory
[haosmos@Haosmos-PC ~]$
But file resolf.conf exist:
cloud.mail.ru/public/5BVW/2zYiramvC
OK. That could be the issue. Judging by your screenshot, you may want to first
rm /etc/resolv.conf
Then can you follow the "Ensure DNS is functioning" part of the article and make sure that two files have been edited appropriately:
/etc/resolv.conf
and/etc/wsl.conf
. Then restart your machine? I am very curious if that works for you or not.After many attempts (a lot of re-installations and reboots of the computer) I finally installed fedora in wsl and set it up)).
Everything seems to be working. I was able to install everything I needed (my goal was to configure the right working environment for web development).
I don't know what the problem was — why I had to start over many times, but wsl (fedora) worked in a strange way: the standard commands didn't work ("cat", "clear", "nano", etc.), or it was impossible to download and install programs and utilities (Curl error (6): Couldn't resolve host name for mirrors.fedoraproject.org/metalink... [Could not resolve host: mirrors.fedoraproject.org].).
Eventually, I set up fedora according to your tutorial, except that I didn't execute the commands:
echo -e "[network]\ngenerateResolvConf = false" > /etc/wsl.conf
and
echo nameserver 1.1.1.1 > /etc/resolv.conf
Now I have this content of the resolv.conf file:
cat /etc/resolv.conf
// This file was automatically generated by WSL. To stop automatic generation of this file, add the following entry to /etc/wsl.conf:
// [network]
// generateResolvConf = false
nameserver 172.29.16.1
In my well-working wsl 2 ubuntu-20.04 the content of the resolv.conf file is exactly the same.
I don't know if this will be a problem in the future (what I didn't specify in the resolv.conf: nameserver 1.1.1 according to your instructions) but so far everything seems to be working fine.
Tell me, please, what do I need to specify in the resolv.conf: nameserver 1.1.1.1 file for?
Maybe I should add it to my resolv.conf file?
Or if everything works as expected I don't have to add or change anything in my resolv.conf file?
Thank you for your feedback! I have updated the DNS section to include more specific instructions for removal of the offending link in Fedora 33, and also prefaced that with acknowledgement of the default automatically-configured
resolv.conf
provided by WSL. I hope this helps!Did you try dnf clean packages as suggested?
[root@operation420.net ~]$ dnf clean all && dnf update
PS I dunno nano, VIM is the hardcore editor/IDE!!!
Did you try dnf clean packages as suggested?
[root@operation420.net ~]$ dnf clean all && dnf update
PS I dunno nano, VIM is the hardcore editor/IDE!!!
Vim is ovekill for simple text editing tasks.
sysctl won't persist after WSL reboot. You can set kernel parameters using
C:\Users\username\.config
or/etc/wsl.conf
(Windows 11 only). (github.com/microsoft/WSL/issues/42...)Seems like you would need to use absolute path to
sysctl
if you are editingwsl.conf
tho becausesysctl
is not loaded to $PATH yet. (github.com/microsoft/WSL/issues/42...)I have updated the article to include this great suggestion, @laoweek. Thank you so much!
Hi, I seem to be having an issue with /etc/resolv.conf
I am running Fedora 36 as instructed here but for some reason I can't unlink to said file because it doesn't exist in the rootfs. If I attempt to write it myself, upon my next access to fedora through wsl, it's just gone... I have to rewrite the file any time that I want use dnf or anything else internet related (which is alot in linux). Can you help me solve this?
Thanks for trying to work through this! First question: do you need to edit /etc/resolv.conf? Have you tried it without making changes?
That is the thing, I don't need to edit /etc/resolv.conf. I need to create it. The file doesn't exist on boot, and every reboot of my system pulls the file system to the default state. So on every reboot, the file doesn't exist... my problem with that is DNF needs the access to the internet and without /etc/resolv.conf their isn't anything, and I tend to do things in steps... so having access to the net on boot is useful.
So, can you confirm: you had no Internet access before you tried changing /etc/resolv.conf?
Also, in /etc/wsl.conf, what is the current
generateResolvConf
set to? True or false?Hopefully we can figure this out!
Well that solved it, it was originally false.... setting it to true corrects things
Thank you for the help
Excellent!
Ok, then maybe you can solve another question that I have.... I also seem to be having trouble with mounting a physical partition on my extra SSD. Keeps tossing out a error, with every attempt to mount it.
Would you have any ideas?
Hmmm... I have not tried to do that. What is the error?
It is tossing out error code -22 when I attempt to use
I can't say I am familiar with that message. It only gives a code and not a complete message? That is odd. Sorry I am not of more help.
I don't know why when I installed Fedora this way, I'm able to write into Windows NTFS (C:/) although it's so slow. But when I installed Ubuntu from the Microsoft Store, I couldn't. Can you give me some insight? Thanks in advance. I found this article very helpful!
Sorry if I am bothering you. I have no idea why. But after running
wsl -t ubuntu
thenwsl -d ubuntu
, now it works. The only thing is it's so slow. Should I move my project folder into WSL ext4 hard disk image file? Or should I just format my D:/ to ext4? What is your advice? Thanks.So, especially in WSL 2, Windows disk performance is very, very poor. Try doing your work in the Linux filesystem (in your home directory, for instance) instead. Is that faster?
Yes, indeed, it is much faster.
Sorry, but I couldn't find
wsl.conf
anywhere. Where should it be?My apologies; I wasn't thinking and gave you wrong advice about the
[interop]
section. That doesn't have anything to do with mounting Windows drives from WSL.Even in out of box supported distros (e.g. Ubuntu) i always found installing distros using Microsoft Store clunky (who wants theirs installs in a folder like: C:\Users<username>\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\ ?), and now you opened my mind about this method.
Many kudos to you!
I agree!