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 WSL 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. Use of WSL version 2 is assumed in this article, though the instructions here might apply to version 1 as well.
Installing WSL
WSL needs to be enabled in Windows before Gentoo can be installed. Here, the --no-distribution
flag prevents the default distribution (Ubuntu) from being installed by default (this can be left out, if desired).
PS >
wsl --install --no-distribution
Please consult Microsoft's documentation for installing WSL on Windows 10 (build 19041 or above) or Windows 11 and older builds of Windows 10.
WSL global options
The path /etc/wsl.conf contains settings for specific Linux distributions (used in various sections below). This file supports four sections: automount, network, interop, and user. However, some settings, such as adjusting memory, number of processors, swap, and host port-forwarding need to be configured within a .wslconfig
file in the Windows user's home directory (e.g. C:\Users\larry\.wslconfig). Here is an example of configuring WSL for these options:
%UserProfile%\.wslconfig
Global options[wsl2]
# Uses the amount specified or the lesser of {8GB OR 50% of the available RAM}
memory=8GB
# see Windows System Information > System Summary > Processor to determine the number available
# Note: should not exceed half of RAM to avoid compilation OOM errors
processors=4
# allow port forwarding (on by default)
localhostforwarding=true
These settings will become important for post-install configuration below (compiler options, etc.). A more complete example of a global configuration file can be found here.
Distributions running as WSL 1 will not be affected by this configuration as they are not running as a virtual machine.
Importing Gentoo via Stage 3 Tarball
The most common way to load a WSL distribution is by installing it using the Microsoft Store, and more specifically, by issuing a command such as wsl --install -d <Distribution Name>
. Run wsl --list --online
to see the available distributions. As Gentoo is not included in this list (as of writing), a more manual approach is used. A stage 3 tarball is used to import a basic Gentoo filesystem. This is similar to a bare-metal installation, where the tarball is unpacked in the soon-to-be mounted filesystem. Assuming WSL is installed and enabled as per the instructions above, the simplified steps are as follows:
- Download, unpack, and import a Stage 3 Tarball.
-
- WSL supports x64 and Arm CPUs. Download the appropriate tarball from the Gentoo downloads page.
- Unpack the tarball using an appropriate tool (e.g. 7-zip - see note below).
- To import Gentoo, open an administrator shell and run
wsl --import <Distro> <InstallLocation> <FileName>
, replacing each parameter with the appropriate value. For example (replacing the file name with your downloaded and unpacked tarball):
PS >
wsl --import Gentoo C:\Users\Larry\AppData\Local\WSL\Gentoo\ .\stage3-amd64-openrc-20211121T170545Z.tar --version 2
Gentoo
: The label of the Linux distribution that will show up in various wsl commands' output (assumed to be "Gentoo" hereafter)C:\Users\Larry\AppData\Local\WSL\Gentoo\
: The path where the WSL files pertaining to Gentoo are to be stored (directory may need to be created first).\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 - may not be required)
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.Basic system and configuration
Initial run
After the stage 3 import, the resulting Gentoo system can be used immediately. Assuming the label given in the import step was "Gentoo", the following command can be used to load the system:
PS >
wsl -d Gentoo
However, some additional steps are highly recommended (next section).
Recommended setup steps
In general, following the Installation Handbook can be used as per usual (post tarball import). Some configuration is not necessary for certain features to work immediately (e.g. networking) and some are not configurable as they are provided automatically or do not apply (e.g. filesystem, bootloader). Some features, such as the init system (see below) and timezone (chrony), can be customized. You can customize your kernel, but this is not discussed in this article. The following sections should be used to finalize the installation process:
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, use /etc/portage/make.conf instead.
- Handbook: AMD64 Installation - Configuring Compile Options
- Handbook: AMD64 Installation - Selecting Mirrors
- Handbook: AMD64 Installation - Configuring Portage
- Handbook: AMD64 Installation - Configuring Locales
- Handbook: AMD64 Installation - Setting Root Password
- Handbook: AMD64 Installation - User Administration — This is still recommended even on WSL; see the relevant Setting up a non-root default user section below.
Per-Distribution WSL Config
The per-distribution file /etc/wsl.conf and global configuration file %UserProfile%\.wslconfig are used to configure advanced settings options. WSL1 and WSL2 can both be configured in /etc/wsl.conf. The file is modelled after ini
syntax. The sections below illustrate a variety of options that can be modified in these files. As an example:
/etc/wsl.conf
Example per-distribution configuration# Automatically mount Windows drive when the distribution is launched
[automount]
# Set to true will automount fixed drives (C:/ or D:/) with DrvFs under the root directory set above. Set to false means drives won't be mounted automatically, but need to be mounted manually or with fstab.
enabled = true
# Sets the directory where fixed drives will be automatically mounted. This example changes the mount location, so your C-drive would be /c, rather than the default /mnt/c.
root = /
# DrvFs-specific options can be specified.
options = "metadata,uid=1003,gid=1003,umask=077,fmask=11,case=off"
# Sets the `/etc/fstab` file to be processed when a WSL distribution is launched.
mountFsTab = true
# Network host settings that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, preventing WSL from the default behavior of auto-generating /etc/hosts, and sets generateResolvConf to false, preventing WSL from auto-generating /etc/resolv.conf, so that you can create your own (ie. nameserver 1.1.1.1).
[network]
hostname = DemoHost
generateHosts = false
generateResolvConf = false
# Set whether WSL supports interop process like launching Windows apps and adding path variables. Setting these to false will block the launch of Windows processes and block adding $PATH environment variables.
[interop]
enabled = false
appendWindowsPath = false
# Set the user when launching a distribution with WSL.
[user]
default = DemoUser
# Set a command to run when a new WSL instance launches. This example starts the Docker container service.
[boot]
command = service docker start
See Advanced settings configuration in WSL for a full description of the options available.
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. To this, it is recommended that a non-root user is enabled and set as the default. The simplest way to set a default user is to create one (if one hasn't been created already):
root #
useradd -m -G wheel larry
root #
passwd larry
and adding the following lines to /etc/wsl.conf:
/etc/wsl.conf
Log in as user larry
when Gentoo is launched on WSL[user]
default=larry
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
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.
Prior to Windows build 18980, an undocumented method to add a default user was accomplished by editing the Windows registry (see https://superuser.com/a/1506322/928571). This method is no longer required.
Init systems
OpenRC can be run on WSL start. Add the following to /etc/wsl.conf:
/etc/wsl.conf
Run OpenRC on WSL start[boot]
command = "/sbin/openrc default"
After a WSL shutdown under Windows:
PS >
wsl --shutdown
services can be enabled and run as per the usual openrc commands.
For Systemd, add:
/etc/wsl.conf
Run systemd on WSL start[boot]
systemd=true
In a similar way, shutdown and restart WSL to use systemd in WSL.
WSL filesystems
By default, existing drives are automatically mounted using the drvfs driver. These drives can be accessed under the /mnt directory.
Performance suffers when working in directories outside of WSL (e.g. /mnt/c/). Therefore, it's recommended that users use the WSL filesystem (e.g. their home directory ~/) instead (see File storage and performance across file systems).
To mount drives not recognized by Windows, read Mount a Linux disk in WSL 2. To mount a USB drive (already mounted on the Windows host), the current method uses usbip which uses the IP protocol to give WSL access to Windows-mounted USB drives. Further instructions can be accessed here.
Graphical programs using X11 or Wayland
Graphical programs can be run under WSL thanks to WSLg (Windows Subsystem for Linux GUI). The purpose of the project is to enable support for running Linux GUI applications (X11 and Wayland) on Windows. The WSLg "system distro" is a containerized Linux environment where the WSLg XServer, Wayland server and Pulse Audio sockets originate. Under a Gentoo client (WSL) distribution, the server is not automatically recognized. To allow for graphical programs, it is necessary to remove the default X11 domain socket, and link to the WSLg socket instead:
root #
rm -r /tmp/.X11-unix && ln -s /mnt/wslg/.X11-unix /tmp/.X11-unix
To verify, users can run a graphical program such as x11-apps/xeyes to confirm.
The X11 domain socket created in this way is not permanent (issue). In order to make this permanent, one solution is to add this command to /etc/wsl.conf:
/etc/wsl.conf
Persist X11 domain socket to enable graphical programs[boot]
command = "rm -r /tmp/.X11-unix && ln -s /mnt/wslg/.X11-unix /tmp/.X11-unix"
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