Configure WSL

Before you can use WSL Dashboard, your Windows system must have WSL 2 properly enabled and configured. This document is divided into three main parts:

1. Enabling and Configuring WSL: Complete the basic installation and configuration of WSL 2.
2. A Working Command Does Not Mean Installation Succeeded: Why being able to run wsl commands doesn't mean Linux can be installed successfully.
3. Troubleshooting Installation Failures: How to check and fix issues when installation still fails after configuration.

1. Enabling and Configuring WSL

This chapter guides you through the necessary basic setup. After completing this chapter, read Chapter 2 to understand the difference between a working command and a successful installation; if you still run into problems, refer to Chapter 3.

1.1 Check System Requirements

WSL 2 has minimum Windows version requirements. Press Win + R and run winver to check your version:

• Windows 10: version 1903 or later, with build number 18362 or higher.
• Windows 11: all versions are supported.

IMPORTANT

If your version is too old, upgrade your system through "Windows Update" first.

1.2 Enable Hardware Virtualization

WSL 2 runs on virtualization technology, so you must enable Virtualization Technology in the motherboard BIOS/UEFI.

• How to check: Open "Task Manager" -> "Performance" tab -> "CPU".
• Check the status: Make sure the "Virtualization" status in the lower-right corner reads "Enabled".
• How to enable: If it is disabled, restart your computer, enter the BIOS/UEFI settings, find an option like Intel VT-x or AMD-V and set it to Enabled.

1.3 Enable the Required Windows Features

You need to turn on "Windows Subsystem for Linux" and "Virtual Machine Platform".

Method A: Through the graphical interface (recommended)

1. Press Win + S, search for and open "Turn Windows features on or off".
2. Check the following two items:
   • Windows Subsystem for Linux
   • Virtual Machine Platform
3. Click "OK" and restart your computer when prompted.

Method B: Through the command line (administrator privileges)

Run PowerShell as administrator and execute the following commands:

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

# Enable the Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

After execution, restart your computer manually.

1.4 Install/Update the WSL Kernel

Modern versions of Windows can get WSL updates through the Microsoft Store.

• Download link: Microsoft Store - Windows Subsystem for Linux
• Manual download: If the Store is unavailable, you can download the latest .msixbundle or .msi package from WSL GitHub Releases for offline installation.

1.5 Set WSL 2 as the Default Version

To ensure newly installed distributions use WSL 2 by default, run the following in a terminal:

wsl --set-default-version 2

1.6 Frequently Asked Questions

• Error 0x80370102: Usually caused by virtualization not being enabled in the BIOS, or a Hyper-V conflict.
• Switching between WSL 1 and WSL 2: You can upgrade an existing WSL 1 instance to WSL 2 with wsl --set-version <distro-name> 2.

2. A Working Command Does Not Mean Installation Succeeded

The fact that commands like wsl --version and wsl -l -v run successfully does not mean your system is ready to install Linux. The two are different stages and cannot be equated.

A working command only means:

• ✅ The WSL components in Windows are already enabled/installed
• ✅ The wsl.exe command-line tool is available
• ✅ The system recognizes WSL-related commands

But installing a Linux distribution successfully requires additional conditions. The common sticking points are:

1. Virtualization is disabled: VT-x / AMD-V is not enabled in the BIOS/UEFI, so WSL 2 cannot start, or installing a distribution reports a virtualization error (check as described in 1.2 Enable Hardware Virtualization).
2. Windows version/build too old: WSL 2 has requirements for the kernel and version; Home editions and overly old enterprise images may be missing features (check as described in 1.1 Check System Requirements).
3. No Linux distribution installed yet: wsl -l -v only lists installed distributions; when nothing is installed the list is empty, which doesn't mean you can run Ubuntu right away.
4. Network / Microsoft Store issues: wsl --install -d <distro> needs to pull images from the Store or the network; corporate networks, proxies, and firewalls can all block it.
5. Insufficient permissions: Installing distributions or modifying WSL settings requires administrator privileges.

TIP

In short: a working WSL command ≠ Linux is ready — you've only got the "ticket", not the actual installed system.

3. Troubleshooting Installation Failures

After completing the configuration in Chapter 1 (or believing you have), if wsl --install still fails, check the following in order.

3.1 Run the "One-Click Check" First

Run PowerShell as administrator and execute in order:

wsl --install --no-distribution
wsl --set-default-version 2

• ✅ If both commands run successfully, the WSL optional components are enabled and the virtualization conditions are essentially met.
• ❌ If they fail, the missing piece (such as Virtual Machine Platform, Hyper-V, or BIOS virtualization) will be reported directly.

Then run systeminfo and confirm the output contains Virtualization Enabled In Firmware: Yes. If none of the above report errors, you can generally proceed with wsl --install to install a distribution.

NOTE

No command can 100% guarantee that wsl --install will succeed, but the checks above confirm whether the installation conditions are met.

3.2 Manual Check Checklist

If the "one-click check" still can't pinpoint the problem, go through the items below:

1. Check whether BIOS/firmware virtualization is enabled: In an administrator PowerShell, run systeminfo; the output must show Virtualization Enabled In Firmware: Yes.
2. Check whether the Windows features are enabled:

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

   Both commands should report Enabled.
3. Check whether WSL is available: wsl --version should produce normal output; if it says the command doesn't exist, the WSL components aren't installed — go back to Chapter 1.
4. Check whether WSL 2 can be used (kernel & Virtual Machine Platform): wsl --set-default-version 2 should return successfully. Common causes of failure: Virtual Machine Platform not enabled, or VT-x / AMD-V not enabled in the BIOS.

3.3 Quick Reference for Common Failure Causes

Situation	Description	How to handle
Virtualization not enabled in BIOS	Will always fail	Restart, enter the BIOS and enable VT-x / AMD-V (see 1.2)
Windows 10 below 19041	wsl --install unsupported	Upgrade the system (see 1.1)
Enterprise environment disables Hyper-V / virtualization	May fail	Contact your system administrator
Old Home edition	Requires manual installation	Manually install the WSL kernel as in 1.4

3.4 Error 0xc03a0014: Cannot Find a Virtual Disk Support Provider

The error message is Cannot find a virtual disk support provider for the specified file. This is not a problem with the Linux distribution itself — the Windows VHD/VHDX virtual disk stack is not working properly, so WSL 2 fails when registering a distribution or creating/mounting ext4.vhdx.

Start with a minimal test: Run PowerShell as administrator and execute a New-VHD test (e.g. New-VHD -Path C:\test.vhdx -SizeBytes 1GB). If this command reports the same error, the problem is 100% on the Windows side and unrelated to the distribution.

Troubleshoot and fix in the following order:

1. Virtual Disk service is not running: Open services.msc, find the Virtual Disk service, set its startup type to "Automatic" and start it.

2. WSL / Virtual Machine Platform features not enabled (or not in effect): Re-run the commands in 1.3 Enable the Required Windows Features, then restart — this is required. Windows Home doesn't have full Hyper-V, but WSL 2 only needs Virtual Machine Platform, not the Hyper-V management interface.

3. Virtual disk driver/device missing: Open Device Manager and check whether the following exist under "System devices / Storage controllers":

   • Microsoft Virtual Disk Provider
   • Microsoft Virtual Drive Enumerator
   • Microsoft VHD Loopback Controller

   If missing, you can add them manually with hdwwiz.exe (Storage controllers → Microsoft → Microsoft VHD Loopback Controller), and make sure the FsDepends service isn't disabled.

4. The imported image doesn't meet WSL requirements: When using wsl --import --vhd, the VHDX must be an ext4 file system — not a LUKS-encrypted disk, a plain raw.img, a Live ISO, or an empty NTFS/FAT-formatted disk. .img / .qcow2 / .iso files cannot be used directly with wsl --import --vhd.

5. Path/permission/file system issues: The target directory must be on an NTFS drive (FAT32/exFAT won't work); avoid Chinese characters, spaces, and special symbols in the path; don't import from network drives, OneDrive, or compressed folders; be sure to use a real administrator PowerShell (not a regular terminal).

6. Corrupted system components: Run DISM and SFC in order to repair system components, then try again:

   DISM.exe /Online /Cleanup-Image /RestoreHealth
   sfc /scannow

TIP

Third-party virtual machines (VirtualBox, VMware) or security software sandbox/hardening features (such as 360, Huorong) may interfere with virtual disk operations; you can temporarily disable them while troubleshooting.