Setup WSL (Windows Subsystem for Linux)

Since Homebrew v2.0 which was released on February 2, 2019, added Windows 10 (WSL) and Linux to the official supported systems.

This article explains that how to setup WSL which is needed by Homebrew.

TOC

Install WSL on Windows 10

Follow these steps to install.

STEP
Select the “Settings” from the Start menu.
STEP
Click “Apps”.
STEP
Click “Programs and Features”.

It is a little confusing to find, but it is located under the “Related settings” section. In the screen capture it is shown in the upper right corner, but if the window is narrower, it will appear below the list of installed apps.

Apps settings
Apps settings
STEP
Click “Turn Windows features on or off”.

It is among the links lined up on the left side of the window that appears.

Programs and Features window
Programs and Features window
STEP
Turn on “Windows Subsystem for Linux” and “Windows Hypervisor Platform” (or “Hyper-V”) and click “OK” button.
Turn Windows features on or off dialog
Turn Windows features on or off dialog
STEP
Installation will begin. When the installation is complete, the message “Windows completed the requested changes.” is displayed. Click the “Restart now” button.
Installation is completed
Installation is completed

Install WSL on Windows 10

Follow these steps to install.

STEP
Click the “Start” button and click the “Settings”.
STEP
Click the “Apps”.
STEP
Click the “Optional features”.
Apps in Settings
Apps in Settings
STEP
Scroll down to bottom, and click “More Windows features” in the “Related settings” section.
Optional features
Optional features
STEP
Turn on “Windows Subsystem for Linux” and ” Windows Hypervisor Platform” , and click “OK” button.
Windows Features dialog
Windows Features dialog
STEP
Installation will begin. When the installation is complete, the message “Windows completed the requested changes.” is displayed. Click the “Restart now” button.
Installation is completed
Installation is completed

Install the Linux distribution

Next, install the Linux distribution to run with WSL, which can be installed from the Microsoft Store.

For the purpose of using Homebrew, any distribution will do. I chose to install Ubuntu because I am familiar with it.

Do following.

On Windows 10

The display changes slightly between Windows 10 and Windows 11, but the operating procedure is the same.

STEP
Search for “Ubuntu” in the Microsoft Store application.
Search result
Search result
STEP
Click the “Ubuntu”. (Free at the time of this writing)
STEP
Click the “Get” button or the “Install” button.

If you have installed the software in the past, the “Install” button will appear; otherwise, the “Get” button will appear.

Ubuntu in Microsoft Store
Ubuntu in Microsoft Store
STEP
Click the “Launch” button.

If you select “Pin to Start” in the notification when the installation is complete, you can start the program from Start.

On Windows 11

The display changes slightly between Windows 10 and Windows 11, but the operating procedure is the same.

STEP
Search for “Ubuntu” in the Microsoft Store Application.
STEP
Click the “Get” button or the “Install” button.

If you have installed the software in the past, the “Install” button will appear; otherwise, the “Get” button will appear.

Ubuntu in Microsoft Store
Ubuntu in Microsoft Store

Setup Ubuntu

When Ubuntu is started, a shell is launched. The first time you start Ubuntu, you will need to set up the Ubuntu side. Follow the steps below to set it up.

STEP
The installation process is executed. Continue to wait.

Depending on the version of Ubuntu, the shell may display the following, or the GUI may display progress.

Installing, this may take a few minutes...
Ubuntu Setup Progress Window
Ubuntu Setup Progress Window

At this point, an error message may appear. Please open the page that is displayed its URL with the error message, follow the instruction to solve the problem, and then start the program again. The error screen can be closed by pressing any key.

Please refer to the section later in this article that describes the error that occurred in my environment.

STEP
After a few moment, the following will appear and you will be asked to wait for a user name to be entered to create a UNIX user account. Enter any user name.
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username:
STEP
Enter the password of the new account.
Enter new UNIX password:
Retype new UNIX password:

Now, you are able to use Ubuntu on WSL.

Update the kernel component

Following error may be displayed.

WslRegisterDistribution failed with error: 0x800701bc
Error: 0x800701bc WSL 2 ???????? ?????????????? https://aka.ms/wsl2kernel ????

Press any key to continue...

This error is displayed when the kernel component is too old. You need to download the latest kernel component from https://aka.ms/wsl2kernel and install it. Do as follows.

STEP
Open https://aka.ms/wsl2kernel .
STEP
Download “WSL2 Linux kernel update package for x64 machines”.

If you use not x64 machines such as ARM64, follow to the web page and download appropriate package.

STEP
Open the downloaded package. The wizard is displayed, click the “Next” button.
Installer Wizard
Installer Wizard
STEP
Installation will begin. Follow the instructions of the wizard. When the completion screen appears, click the “Finish” button.
Completion screen
Completion screen

When virtualization support functions need to be enabled in the BIOS/UEFI

When the virtualization support is disabled in the BIOS or UEFI, the following error is displayed.

WslRegisterDistribution failed with error: 0x80370102
Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS.
For information please visit https://aka.ms/enablevirtualization
STEP
Enable the virtualization function in the BIOS or UEFI.

Please see your machine’s manual. For example, in the case of my Dell machine, you will find the following items in the BIOS menu.

  • Enable Intel Virtualization Technology
  • Enable VT for Direct I/O
STEP
Launch the PowerShell with the administrator rights.
STEP
Run following in the PowerShell to check the Hypervisor is enabled.
bcdedit /enum | findstr -i hypervisorlaunchtype

When the Hypervisor is disabled, following message will be displayed.

hypervisorlaunchtype Off

Run following to enable the Hypervisor.

bcdedit /set {current} hypervisorlaunchtype Auto

If any message is not displayed, the needed components may be not installed. First, run following to check whether your machine supports Hypervisor.

systeminfo.exe

A lot of informations are displayed, check the Hyper-V Requirements. If the output is as follows, the machine is Hyper-V compliant.

Hyper-V Requirements: VM Monitor Mode Extensions: Yes
                      Virtualization Enabled In Firmware: Yes
                      Second Level Address Translation: Yes
                      Data Execution Prevention Available: Yes

If you are getting an error in this situation, Hyper-V is most likely not installed. Follow the WSL installation instructions in this article to install “Hyper-V” or “Windows Hypervisor Platform”.

If the output is as follows, the Hyper-V is already enabled.

Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not displayed.
Let's share this post !

Author of this article

Akira Hayashiのアバター Akira Hayashi Representative, Software Engineer

I am an application developer loves programming. This blog is a tech blog, its articles are learning notes. In my work, I mainly focus on desktop and mobile application development, but I also write technical books and teach seminars. The websites of my work and books are here -> RK Kaihatsu.

TOC