Installation Instructions for WSL 2

To install and start using WSL 2 complete the following steps:

WSL 2 is only available in Windows 10 builds 18917 or higher

  • Ensure that you have WSL installed (you can find instructions to do so here) and that you are running Windows 10 build 18917 or higher
    • To make sure you are using build 18917 or higher please join the Windows Insider Program and select the 'Fast' ring.
    • You can check your Windows version by opening Command Prompt and running the ver command.
  • Enable the 'Virtual Machine Platform' optional component
  • Set a distro to be backed by WSL 2 using the command line
  • Verify what versions of WSL your distros are using

Enable the 'Virtual Machine Platform' optional component and make sure WSL is enabled

Open PowerShell as an Administrator and run:

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

This will make sure that both the Virtual Machine Platform and Windows Subsystem for Linux optional components are installed. After you've run these commands you'll need to restart your computer.

Set a distro to be backed by WSL 2 using the command line

In PowerShell run:

wsl --set-version <Distro> 2

and make sure to replace <Distro> with the actual name of your distro. (You can find these with the command: wsl -l). You can change back to WSL 1 at anytime by running the same command as above but replacing the '2' with a '1'.

Additionally, if you want to make WSL 2 your default architecture you can do so with this command:

wsl --set-default-version 2

This will make any new distro that you install be initialized as a WSL 2 distro.

Finish with verifying what versions of WSL your distro are using

To verify what versions of WSL each distro is using use the following command (only available in Windows Build 18917 or higher):

wsl --list --verbose or wsl -l -v

The distro that you've chosen above should now display a '2' under the 'version' column. Now that you're finished feel free to start using your WSL 2 distro!

Troubleshooting:

Below are related errors and suggested fixes when installing WSL 2. Please refer to the WSL troubleshooting page for other general WSL errors and their solutions.

  • Installation failed with error 0x80070003 or error 0x80370102

    • Please make sure that virtualization is enabled inside of your computer's BIOS. The instructions on how to do this will vary from computer to computer, and will most likely be under CPU related options.
  • Error when trying to upgrade: Invalid command line option: wsl --set-version Ubuntu 2

    • Please make sure that you have the Windows Subsystem for Linux enabled, and that you're using Windows Build version 18917 or higher. To enable WSL run this command in a Powershell prompt with admin privileges: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux. You can find the full WSL install instructions here.