Configuring WSL

WSL configuration is done in 1 of 2 places:

• On the host side, editing C:\Users\<username>\.wslconfig
  • This file configures the WSL machine, and applies to all distributions installed.
  • This is where you set options like guiApplications, localhostForwarding, etc.
• On the WSL side, by editing /etc/wsl.conf
  • Configures options for the specific distribution you edit this file from.
  • Set options like the default user, enable systemd, and more

Host configurations (C:\Users\.wslconfig)

Global configurations

• Microsoft Docs: Global WSL configuration

Enable GUI apps in WSL

You can add support for graphical programs (instead of just a Bash CLI) by enabling guiApplications

[wsl2]
guiApplications=true

Enable/disable Windows firewall rules in WSL

WSL can use the Windows Firewall rules when firewall is enabled.

[wsl2]
firewall=true

[wsl2]
firewall=false

Limit WSL memory

[wsl2]
memory=4GB

Set WSL swap amount

[wsl2]
swap=8GB

You can also set a swap file disk on the host. The default is %USERPROFILE%\AppData\Local\Temp\swap.vhdx.

Set swap file

swapfile=C:\\temp\\wsl-swap.vhdx

Disable WSL page reporting

Disabling page reporting for WSL causes it to retain all allocated memory claimed from Windows, releasing none back when free. NOT RECOMMENDED

[wsl2]
pageReporting=false

Forward Windows host network connection to WSL

Turn on default connection to bind WSL 2 localhost to Windows localhost. Setting is ignored when networkingMode=mirrored

[wsl2]
localhostforwarding=true

Enable/disable nested virtualization, i.e. Docker in WSL

[wsl2]
nestedVirtualization=true

[wsl2]
nestedVirtualization=false

WSL distribution configurations (/etc/wsl.conf)

Configurations per-distribution.

• Microsoft Docs: wsl-config

Disable joining Windows path

WSL will attempt to join the Windows PATH variable with its own $PATH. This can lead to unexpected behavior, like if pyenv is installed in both Windows and WSL.

To fix this, disable the appendWindowsPath flag in the [interop] section of /etc/wsl.conf

## /etc/wsl.conf

...

[interop]
appendWindowsPath = false

...

Set default user

Note

To set a default user inside the WSL distribution, the user account must exist. When you first run a WSL container, you will be prompted to create a user account.

You can create additional users with the useradd command:

sudo adduser <username>

[user]
default=<username>

Enable systemd

[boot]
systemd=true

Enable/disable automounting of Windows drives

By default, Windows will mount all fixed drives (i.e. C:\, D:\, etc) in the container at /mnt/<driveletter>. This feature can be controlled with the enabled flag in [automount]

[automount]
enabled=true

[automount]
enabled=false

Control mounts from within WSL's /etc/fstab

To mount extra paths inside the WSL container, i.e. an SMB share, you can modify the /etc/fstab the same way you would on a "full" Linux install, but you must also enable mountFsTab.

[automount]
mountFsTab=true

[automount]
mountFsTab=false

Control default root directory

When starting up a WSL distribution, your terminal's CWD will be the path you ran wsl from in Windows. For example, if you are in C:\Users\<user> and run wsl, the WSL distribution's prompt will be /mnt/c/Users/<user>.

The default WSL root directory is /mnt. To set a different path, edit the root flag in the [automount] section.

[automount]
root=/home/<user>

Set a hostname for WSL distribution

By default, the WSL distribution's hostname will be the same as the Windows host. This can be modified by changing the hostname flag in the [network] section.

[network]
hostname="your-hostname"