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 (Enter %USERPROFILE% in file explorer's location bar).

For example,

.wslconfig

[wsl2]
memory=20GB              # How much memory to assign to the WSL2 VM.
processors=4             # How many processors 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 (Enter %USERPROFILE% in file explorer's location bar). ⁴

.wslconfig

[experimental]
autoMemoryReclaim=dropcache  # 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

diskpart¶

Alternatively, use diskpart (if Optimize-VHD is not available) ⁶

wsl --shutdown
diskpart
# open window Diskpart
select vdisk file="E:\ubuntu\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

Export and re-import¶

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

Caveats about WSL2¶

Memory cost of running Hyper-V¶

Hyper-V may reserve 1 GB of RAM. Web archive

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/).⁷