Gentoo in WSL
This page documents the process and some configuration tips to get Gentoo running on WSL (Windows Subsystem for Linux) - to effectively run Gentoo under Windows.
Since WSL2 uses a real Linux kernel running on top of a hypervisor, Linux is essentially run within Windows. Gentoo can run on top of WSL too.
Installing WSL on Windows
WSL needs to be installed before Gentoo can be imported and set up in it. Use of WSL version 2 is assumed in this article, though the instructions here might apply to version 1 as well.
Please consult Microsoft's documentation for installing WSL on Windows 10 (build 19041 or above) or Windows 11 and older builds of Windows 10.
Importing a stage 3 tarball into WSL
A stage 3 tarball is required to install Gentoo in WSL. Download the appropriate tarball for system architecture at the Gentoo downloads page.
A command like the following one, which should be run in Windows PowerShell, imports a Gentoo stage 3 tarball into WSL.
PS >
wsl --import Gentoo C:\Users\Larry\AppData\Local\WSL\Gentoo\ .\stage3-amd64-openrc-20211121T170545Z.tar --version 2
Some arguments in this command that can or should be changed are:
Gentoo
: The name of the Linux distribution that will show up in various wsl commands' outputC:\Users\Larry\AppData\Local\WSL\Gentoo\
: The path where the WSL files pertaining to Gentoo are to be stored.\stage3-amd64-openrc-20211121T170545Z.tar
: The path to the stage 3 tarball--version 2
: The WSL version being used for the imported distribution (which is 2 in this example)
The stage 3 tarball passed into the wsl command should have
.tar
file name extension. Stage archives on Gentoo mirrors are .xz
archives, but they can be unpacked to produce the .tar
file. On Windows, programs that can unpack .xz
archives include 7-Zip.Configuring the Gentoo distribution imported into WSL
Initial setup
After the stage 3 import, the resulting Gentoo system in WSL still requires some additional initial setup steps. First, enter the Gentoo distribution on WSL by using the command:
PS >
wsl -d Gentoo
The system can be configured as desired by following the Installation Handbook for steps following installing stage 3. Some configurations — like init system, timezone, kernel, filesystem, networking, and bootloader — are not necessary as they are managed by WSL. Only the sections listed below are relevant on WSL; instructions in all other sections may be ignored.
- Handbook:AMD64/Installation/Stage#Configuring compile options
- Handbook:AMD64/Installation/Base#Optional: Selecting mirrors
- Handbook:AMD64/Installation/Base#Configuring Portage
- Handbook:AMD64/Installation/Base#Configure locales
- Handbook:AMD64/Installation/System#Root password
- Handbook:AMD64/Installation/Finalizing#User administration — This is still recommended even on WSL; see the relevant #Setting up a non-root default user section below for more details.
Because configuration on WSL does not involve chrooting, whenever the handbook mentions a path that starts with /mnt/gentoo, that prefix should be dropped from the path. For example, when the handbook says /mnt/gentoo/etc/portage/make.conf, please use /etc/portage/make.conf instead.
Now a basic Gentoo system setup in WSL should be achieved. The resulting Gentoo system could be used like if it was on the bare-metal: more packages can be installed, and it might even be possible to run GUI apps thanks to WSLg, a new WSL 2 feature.
Setting up a non-root default user
When starting Gentoo in WSL, the root user will be used by default. This is neither secure nor preferable. It would be better if WSL would use a non-privileged user as default.
There are alternative ways to specify the default user. Configuration specified in /etc/wsl.conf will be preserved when exporting/importing a distribution which makes it less suitable for creating templates. Specifying a default user in the Windows Registry will be lost on export/import and will need to be repeated if the instance is re-imported.
After configuring a default user, a root session can still be explicitly started by specifying a user in the wsl command. For example:
PS >
wsl -u root -d Gentoo
Creating a new non-root user
A new non-root user in the wheel group needs to be created first; this is also what WSL prompts the user to do when one of the prepackaged distributions downloaded from the Microsoft Store is launched for the first time. Replace larry
with a desired user name.
root #
useradd -m -G wheel larry
root #
passwd larry
Specifying the default WSL user in the Windows Registry
Start the Registry Editor and navigate to HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss. Within the keys within Lxss, search for the one with a DistributionName string equal to what was used to install Gentoo. Within that key, look for a DWORD named DefaultUid. Create it if it's missing, then set it to the uid to use by default (usually 1000 for the first user created). Note that regedit defaults to hexadecimal for DWORDs; switch to decimal before punching in 1000 (or punch in 3e8).
Specifying the default WSL user in /etc/wsl.conf
Create a file called /etc/wsl.conf in the Gentoo system on WSL with the following contents.
/etc/wsl.conf
Log in as user larry
when Gentoo is launched on WSL[user] default=larry
Replace larry
with the appropriate user name.
Exit Gentoo back to the shell, and then issue wsl --terminate Gentoo. The change in /etc/wsl.conf should then take effect the next time Gentoo is launched.
WSL 2 can be configured in ways such as adjusting the memory allocation since it essentially runs a Linux distribution in a virtual machine. Here is an example of configuring the virtual machine:
/etc/wsl.conf
Allocate 8 GB RAM and 4 virtual processors to Gentoo on WSL 2[wsl2] memory=8GB processors=4
Troubleshooting
An error occurred mounting one of the file systems
If a new Gentoo installation on Windows 11 fails to start with this error message:
PS >
wsl -d Gentoo
An error occurred mounting one of your file systems. Please run 'dmesg' for more details.
Then reinstall Gentoo using a nomultilib
stage3 variant.
Segmentation fault in docker
If using a docker image with some old glibc distributions inside Gentoo in WSL, segmentation faults may occur. In most cases this happens because vsyscall is off by default. Workaround is to enable its emulation at global WSL configurationː
%UserProfile%\.wslconfig
Enable vsyscall emulation[wsl2] kernelCommandLine = vsyscall=emulate
Problems with network with active Cisco AnyConnect VPN
If the VPN has no routes to the internet (only intranet), then change VPN interface metrics after each reconnect. Otherwise all traffic from WSL will go to VPN interface. This can be done with the next command on Windowsː
PS >
Get-NetAdapter | Where-Object {$_.InterfaceDescription -Match "Cisco AnyConnect"} | Set-NetIPInterface -InterfaceMetric 6000