WSL Cheat-Sheet

Windows Subsystem for Linux. Commands run in PowerShell (PowerShell Cheat-Sheet) unless noted.

Manage Distros #

Backup and Restore WSL #

Backup a WSL Distro #

wsl --export (distribution) (filename.tar)

Restore a WSL Distro from Backup #

wsl --import (distribution) (install location) (file location and filename)

Symbolic Links #

Replace <WINUSER> with your Windows user name.

Link .ssh folder #

ln -s /mnt/c/Users/<WINUSER>/.ssh ~/.ssh

Link .kube folder #

ln -s /mnt/c/Users/<WINUSER>/.kube ~/.kube

SSH insists on strict key permissions, which NTFS mounts do not provide unless metadata is enabled (below). Copying keys into ~/.ssh is often simpler.

File Permissions #

Advanced settings configuration in WSL: WSL Config Parameters

Example /etc/wsl.conf (per distro, run wsl --shutdown to apply)

[automount]
enabled = true
options = "metadata,uid=1000,gid=1000,umask=077,fmask=11,case=off"
mountFsTab = true

[interop]
enabled = false
appendWindowsPath = false

Example %UserProfile%\.wslconfig (global, WSL 2)

[wsl2]
memory=8GB
processors=4
swap=2GB
networkingMode=mirrored

Resource Limits (.wslconfig) #

WSL 2 runs in one lightweight VM, shared by all distros. Limits go in %UserProfile%\.wslconfig on Windows (not inside the distro). Run wsl --shutdown and wait a few seconds for changes to apply.

[wsl2]
memory=8GB                 # default: 50% of Windows RAM
processors=4               # default: all logical processors
swap=4GB                   # 0 disables swap
swapFile=D:\\wsl\\swap.vhdx
vmIdleTimeout=60000        # ms before the idle VM stops
localhostForwarding=true   # NAT mode: reach WSL services at localhost
nestedVirtualization=true  # run KVM or Docker in WSL (Windows 11)

[experimental]
autoMemoryReclaim=gradual  # return unused cache to Windows (or dropcache, disabled)
sparseVhd=true             # new distro disks shrink automatically

Disk and memory housekeeping:

systemd in WSL #

Recent WSL versions (check wsl --version; needs WSL 0.67.6 or newer from the Store build) can run systemd as PID 1, so systemctl, services and snap work. Enable it per distro in /etc/wsl.conf (inside Linux):

[boot]
systemd=true
command="service cron start"   # optional: run a command at distro start

Then restart the distro from PowerShell: wsl --shutdown.

Notes: the distro still stops when its last terminal closes and the idle timer elapses; services only run while the VM runs. Keep it alive with wsl -d <DISTRO> --exec sleep infinity in a hidden task, or a scheduled task at logon. Newer Ubuntu images enable systemd by default. See Linux Basics for systemd commands.

Networking Modes #

Set the mode in .wslconfig under [wsl2] with networkingMode=.

Companion settings:

[wsl2]
networkingMode=mirrored
dnsTunneling=true      # resolve names through Windows, helps with VPN and split DNS
autoProxy=true         # use the Windows proxy settings
firewall=true          # apply Windows firewall rules to WSL traffic

[experimental]
hostAddressLoopback=true   # NAT mode: reach Windows from WSL via the host IP

In mirrored mode inbound connections from the LAN are filtered by the Hyper-V firewall. Allow them in an elevated PowerShell:

Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow
# or open only one port
New-NetFirewallHyperVRule -Name "WSL-8080" -DisplayName "WSL 8080" -Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -Protocol TCP -LocalPorts 8080

Windows networking commands are in Windows Networking. If DNS breaks, set generateResolvConf = false under [network] in /etc/wsl.conf and write your own /etc/resolv.conf, or use dnsTunneling. If you see a /etc/resolv.conf that points at a stale IP, run wsl --shutdown.

Port Forwarding (NAT mode) #

Find IP Address

bash.exe -c "ifconfig eth0 | grep 'inet '"

Add PortForwarding (use the WSL IP found above as $remoteaddr)

$port = 8080
$remoteaddr = "172.20.10.2"

netsh interface portproxy add v4tov4 listenport=$port connectport=$port connectaddress=$remoteaddr

netsh advfirewall firewall add rule name=$port dir=in action=allow protocol=TCP localport=$port

Delete PortForwarding

$port = 8080

netsh interface portproxy delete v4tov4 listenport=$port
netsh advfirewall firewall delete rule name=$port

Show PortForwardings

netsh interface portproxy show v4tov4

Useful Interop #

Linux desktop in WSL2 #

With WSL2 it’s possible to install and run a Linux desktop environment (XFCE). A tutorial on how to implement that, can be found here.

Not Verified #

The resource, systemd and networking sections were written from the Microsoft WSL documentation and not executed. Options such as autoMemoryReclaim, sparseVhd, dnsTunneling and wsl --manage --resize need a recent WSL release (wsl --update).