Gentoo in WSL
This page documents the process and some configuration tips to get Gentoo running on WSL (Windows Subsystem for Linux).
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.
Importing a stage 3 tarball into WSL
A command like the following one, which should be run in Windows PowerShell, imports a Gentoo stage 3 tarball into WSL.
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' output
C:\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
.tarfile name extension. Stage archives on Gentoo mirrors are
.xzarchives, but they can be unpacked to produce the
.tarfile. On Windows, programs that can unpack
.xzarchives include 7-Zip.
Configuring the Gentoo distribution imported into WSL
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:
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:
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.
useradd -m -G wheel 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 you 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 you want to use by default (usually 1000 for the first user created). Note that regedit defaults to hexadecimal for DWORDs; you'll want to switch to decimal before you punch in 1000 (or you can 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.
larry with the appropriate user name.
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:
[wsl2] memory=8GB processors=4
If a new Gentoo installation on Windows 11 fails to start with this error message:
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.