Windows subsystem for Linux 2 (WSL2)

Set up Windows subsystem for Linux 2 (WSL2) for Linux development experience in Windows 10 and 11.

Instal WSL2¶

Open powershell with administrator privilege, run the following command in the host.

wsl --install --no-distribution

or install the components manually

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

After reboot, install the Linux distribution

wsl --update
wsl --set-default-version 2
wsl --install -d Ubuntu  # Or another Linux distribution

WSL2 post-install (optional) setup¶

Backup/move the virtual disk¶

If you want to move the WSL virtual disk file to another disk (in this example, D:\), run the following commands in Windows¹²:

wsl --export Ubuntu .\Ubuntu\ext4.tar
wsl --unregister Ubuntu
wsl --import Ubuntu D:\Ubuntu\ .\Ubuntu\ext4.tar

Edit /etc/wsl.conf in the WSL. You may need to set the default user if you have moved the virtual disk file of the WSL distribution.

/etc/wsl.conf

[user]
default=username

Host settings¶

Edit .wslconfig ³ in your Windows home directory (%USERPROFILE%).

For example,

.wslconfig

[wsl2]
memory=20GB              # How much memory to assign to the WSL2 VM.
swap=8GB                 # How much swap space to add to the WSL2 VM. 0 for no swap file.
swapfile=C:\\temp\\wsl-swap.vhdx # Sets swap file path location, default is %USERPROFILE%\AppData\Local\Temp\swap.vhdx. Useful if your C drive has limited disk space.

Auto reclaim RAM and disk space¶

Edit .wslconfig ³ in your Windows home directory (%USERPROFILE%). ⁴

.wslconfig

[experimental]
autoMemoryReclaim=gradual    # Reclaim RAM usage
sparseVhd=true               # Reclaim virtual disk (vhd) usage

Maintenance¶

Update kernel¶

To (manually) update the WSL kernel, run the following commands with administrator privileges:

wsl --shutdown
wsl --update

Reclaim virtual disk space¶

Optimize-VHD¶

Note

Optimize-VHD is not available in Windows Home edition.

To reclaim disk space from virtual hard disks (VHDs), run the following commands with administrator privileges ⁵:

wsl --shutdown
Optimize-VHD -Path %path-to.vhdx% -Mode Full

Export and re-import¶

Alternatively, export the VHD as a tar file and reimport it again.

Caveats about WSL2¶

Poor filesystem performance across OSes¶

Cross-OS file access (e.g., accessing /mnt/c in WSL) is at least one order of magnitude (10x) slower than accessing natively (/home/user/).⁷