To resolve Windows Subsystem for Linux (WSL) installation issues, verify your Windows build is 19041 or higher and ensure virtualization is enabled in the BIOS. Run
wsl --install with administrative privileges, then restart your machine. If specific distributions fail, check the Windows Store for errors or use
wsl --set-version to convert legacy WSL instances to WSL 2, which resolves most compatibility and initialization failures during setup.
Prerequisites for a Successful WSL Installation
Before attempting to install any Linux distribution, you must confirm that your system meets the minimum requirements. The most common reason for installation failure is running an outdated version of Windows 10 or an unsupported version of Windows 11. For Windows 10, you need version 2004 or higher, with build number 19041 or later. For Windows 11, any version works as long as it is up to date. You can check your current build by pressing
Win + R, typing
winver, and hitting Enter.
Virtualization support is another critical component. WSL 2 relies on the Hyper-V platform, which requires hardware virtualization to be enabled in your computer’s BIOS or UEFI settings. If this feature is disabled, the installation will silently fail or throw generic errors. To verify if virtualization is active, open Task Manager, go to the Performance tab, and look at the CPU section. It should explicitly state "Virtualization: Enabled." If it says Disabled, you will need to reboot into your BIOS/UEFI menu and enable Intel VT-x or AMD-V depending on your processor manufacturer.
Using the Automated Installation Command
The modern and recommended method for installing WSL is using the single command line instruction provided by Microsoft. Open PowerShell or Command Prompt as an Administrator. This elevation is mandatory because the process involves creating kernel modules and configuring network adapters. Type the following command and press Enter:
wsl --install
This command performs several actions automatically. It enables the necessary Windows features, including the Virtual Machine Platform and Windows Subsystem for Linux. It also downloads and installs the default Linux distribution, which is typically Ubuntu. After the command completes successfully, you must restart your computer. This reboot is essential for the new kernel drivers to load correctly into the operating system. Without a restart, subsequent attempts to launch the Linux environment may result in unexpected errors or performance degradation.
Troubleshooting Common Error Codes
If the automated installation fails, you will likely see specific error codes that guide your next steps. One frequent issue is related to network connectivity or corrupted Windows components. If you encounter an error indicating that the service could not be started, try resetting the Windows Update components by running
sfc /scannow in an elevated command prompt. This checks for and repairs corrupted system files that might prevent the WSL features from activating.
Another common scenario involves conflicts with existing virtualization software. Applications like VMware Workstation or Oracle VirtualBox sometimes conflict with the Hyper-V backend used by WSL. If you are using these tools, ensure they are updated to their latest versions, as newer releases often include better integration with Windows virtualization layers. In some cases, disabling these third-party hypervisors temporarily allows the WSL installation to proceed without interference.
For users who previously installed WSL 1 and are upgrading, conversion issues may arise. You can manually convert an existing distribution to WSL 2 using the command
wsl --set-version <DistroName> 2. Replace
<DistroName> with the actual name of your distribution, such as Ubuntu-20.04. This step ensures that your existing data is preserved while gaining the benefits of the WSL 2 architecture.
Manual Installation via Microsoft Store
In situations where the command-line installer fails due to network restrictions or corporate policies, you can manually install distributions from the Microsoft Store. Search for your desired Linux distribution, such as Kali Linux, Debian, or SUSE Linux Enterprise Server. Click "Get" or "Install" to download the package. Once installed, launch the application from the Start Menu. The first time you run a newly installed distribution, it will extract its file system and ask you to create a Unix username and password.
This manual approach gives you more control over which specific version of a Linux distribution you want to run. It is particularly useful if you need a distribution that is not included in the default list provided by the
wsl --install command. However, note that you still need to have the underlying WSL features enabled in Windows before you can launch these stores apps. If launching the app results in an error, refer to our guide on fixing WSL not initializing due to systemd-firstboot.service for deeper diagnostic steps.
Verifying the Installation
After installation and reboot, verify that WSL is working correctly. Open PowerShell and type
wsl -l -v. This command lists all installed distributions along with their status and version. A healthy installation will show your distribution listed with Version 2. If it shows Version 1, remember to convert it as described earlier. You can also simply type
wsl to enter the Linux shell. If you see a prompt ending in
$ or
#, your installation is successful.
Frequently Asked Questions
Why does my WSL installation hang at 99%?
This usually indicates a network timeout or a corrupted download cache. Try clearing the Windows Update cache by stopping the wuauserv service and deleting contents of C:\Windows\SoftwareDistribution\Download. Then retry the installation command.
Can I install WSL on Windows 10 Home?
Yes, WSL is fully supported on Windows 10 Home edition. However, you must ensure your build is 19041 or higher. Some advanced features available in Pro or Enterprise editions, such as nested virtualization, may not be accessible on Home versions.
What should I do if I get an 'Invalid Argument' error on /etc/passwd?
This specific lock error often occurs when multiple processes try to access user data simultaneously. Refer to our article on fixing the WSL 'Failed to take /etc/passwd lock' error for detailed steps on resolving permission conflicts and ensuring clean shutdowns of Linux instances.
How do I change the default Linux distribution?
You can set a specific distribution as the default by using the command
wsl --set-default <DistroName>. Replace
<DistroName> with the exact name shown in
wsl -l -v. This ensures that typing just
wsl launches your preferred OS.
Is it safe to uninstall WSL completely?
Yes, you can remove WSL by running
wsl --unregister <DistroName> to delete the instance, followed by disabling the optional features in Windows Settings. Be aware that unregistering a distribution deletes all files and data within that Linux environment permanently.