Install or reinstall Windows Subsystem for Linux

Ubuntu LTS releases among other Linux distros are available on the Microsoft Windows Store. This procedure describes how to install WSL2, which requires at least Windows 10 20H1 2004, released to the general public on 27 May 2020.

WSL images can be switched between WSL1 and WSL2.

Install

  1. in Administrator PowerShell:

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

  3. in Administrator PowerShell:

    dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
    
  4. reboot PC again

  5. from PowerShell (admin not needed)

    wsl --set-default-version 2
    

    you may be prompted to manually update the WSL kernel.

  6. go to Microsoft Store and install Ubuntu (or other Linux distro)

  7. start the default Linux distro by clicking the Start Menu icon (e.g. Ubuntu), or type in Windows Command Prompt:

    wsl
    

Verify WSL version

Verify if on WSL1 or WSL2 by from PowerShell / Command Prompt:

 wsl --list --verbose

The result will be like:

  NAME      STATE           VERSION
* Ubuntu    Running         2

switch WSL version

Convert an existing WSL1 distro to WSL2 from PowerShell:

wsl --set-version Ubuntu 2

Before doing this, set %userprofile%.wslconfig to include:

[wsl2]
swap=0GB

Else the process may take 15..20 minutes.

configure WSL

per distro /etc/wsl.conf

A WSL default that is confusing and slows down WSL program-finding is stuffing Windows PATH into WSL PATH. We normally disable Windows PATH injection into WSL, because it also breaks library finding in build systems like CMake. Additionally, we enable filesystem metadata, as weird permission errors can occur, even causing CMake to fail to configure simple projects.

Each Linux distro has its own /etc/wsl.conf We typically include in our /etc/wsl.conf:

[automount]
enabled = true
options = "metadata"

[interop]
enabled=false
appendWindowsPath=false

global ~/.wslconfig

The %USERPROFILE%.wslconfig file sets parameters for all Linux distros, versus the per distro /etc/wsl.conf discussed above. To avoid the use of Linux swap and excessive memory thrashing we include in Windows ~/.wslconfig:

[wsl2]
swap=0GB

Examples

Run Ubuntu apps from Windows Command Prompt

From Windows Command Prompt (or PowerShell) can run Linux commands like “ls -l”:

wsl ls -l

Run Windows program from Ubuntu app

From Ubuntu terminal

/mnt/c/Windows/System32/notepad.exe
  • capitalization matters
  • you must include the .exe at the end.

Reinstall Ubuntu

  1. copy off your Linux user files (the next step deletes them).

  2. Command Prompt:

    Ubuntu clean
    
  3. Command Prompt:

    Ubuntu
    

List installed Windows Linux distros

Install, list, and switch between Linux distros on Windows default for bash by from Command Prompt:

wslconfig

Notes

Fix Error: 0x80040154

If you’ve just upgraded to a new Windows Build, try from Administrator PowerShell:

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