Resolving errors of installing Linux with WSL

You may meet errors when trying to install Linux with WSL even your Windows has satisfied the prerequisites:

Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11.

Why using WSL

WSL allows you have a Linux distribution, Linux applications, a Bash command line tool without the overload of the traditional virtual machine or dual-systems.

wsl --install error – Invalid command line option: –install

C:WINDOWSsystem32>wsl --install
Invalid command line option: --install
Usage: wsl.exe [option] ...

That’s because your Windows version is not recent enough. According to Set up a WSL development environment:

To use the simplified –install command, you must be running a recent build of Windows (Build 20262+). To check your version and build number, select Windows logo key + R, type winver, select OK. You can update using the Settings menu or Windows Update Assistant.

If you do not intend to update your Windows, try WSL manual installation steps for older versions. Just follow its step1-step6 to install WSL2 if your Windows version satisfy the needs in step2, otherwise do step1 and jump to do step6 to install WSL1.

Error – The packaged version of WSL is not supported by windows-version

If you try to install WSL from Windows Store and meet below error:

The packaged version of WSL is not supported by windows-version

Try manual install with step1-step5 (or just step1 if your windows do not meet the needs in step2) introduced in WSL manual installation steps for older versions. Then jump to the bottom “Downloading distributions” section to manually download a Linux distribution.

Like to download the Ubuntu 20.04, direct to the folder you want to put the distribution file and run:

$ curl.exe -L -o ubuntu-2004.appx

The download may fail, try a few more times.

When the download is done, use Add-AppxPackage .ubuntu-2004.appx or double click the ubuntu-2004.appx file to install it.

You will see a Ubuntu command line to prompt you it is installing and then prompt you to set a username and password for the Linux:

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit:
Enter new Unix username:

Note you won’t see the newly installed instance command line in Windows Terminal for a manual install. You need to manually set up a profile for the new instance to see its command line in Windows Terminal.

See more at Set up a WSL development environment for more settings like Visual Studio Code, Git, MySQL, etc.

Install Windows Terminal

It is recommended to install Windows Terminal. Windows Terminal can run any command line tool and open them in multiple tabs. Then you are able to easily switch between multiple tasks like between Linux distribution command line and Windows Command Prompt.

It can be installed from Windows Store. Once it is stalled, you can see many command lines in it like PowerShell, Windows Prompt and any Linux instance command line (if it is not a manual WSL install).

For manual Linux install WSL, manually set up a profile for it to integrate it in Windows Terminal.

Set up a profile for a manual install of Linux instance

To set up a profile for Ubuntu:

  1. Windows Terminal > Drop down button > Settings.

  2. New empty profile

  3. Set the name like “Ubuntu” and command line (the path of ubuntu.exe).

  4. Save

Then the command line tool will present in Windows Terminal menu.