31. Windows Subsystem for Linux (WSL)

Windows Subsystem for Linux (WSL) enables the ability to install a pseudo distribution of linux on windows using a fully suppported (Microsoft built) kernel; replaces the need for Cygwin.

WSL2 runs a real linux kernel which increases performance and compatiblity. It is preferred over WSL1. WSL references the WSL2 installation.

See Forwarding X Windows to setup a Windows 10 X server to display WSL applications on the Windows desktop.



31.1. Enable WSL in Windows 10

Enable WSL on Windows (powershell as admin).
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart


Force update Windows after this step.

Windows versions up to 1909 must install KB4566116. Determine Windows Version if needed.

Enable WSL on Windows up to 1909 (powershell as admin).
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart
Enable WSL on Windows 2004+ (powershell as admin).
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Install x64 kernel update for WSL2.

Set WSL2 as default.
wsl --set-default-version 2


31.2. Installing Linux Distros

Only custom linux distros built for the Windows Linux Kernel are supported.

Manual Install

See Manual Install for list of available pre-built distros.

Download Appstore package and install (powershell as admin).
curl.exe -L -o {DISTRO}.appx https://aka.ms/wsl-{DISTRO}
Add-AppxPackage .\{DISTRO}.appx

Launch the distro to complete installation.

Windows Store Install

This automatically installs a given distro but requires login to the Microsoft Store.

⌘ › Microsoft Store › Search › {DISTRO}

Launch the distro to complete installation.


31.3. Troubleshooting

Installation failed with error 0x80070003

WSL is only intended to run on the system drive (usually c:\). WSL was installed to a different drive.

Then reinstall your distro.

WslRegisterDistribution failed with error 0x8007019e

WSL is not enabled. See Enable WSL in Windows 10.