Setup & Config WSL

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

1. Setup & Config WSL: Complete the basic installation and configuration of WSL 2.
2. Command Availability Does Not Equal a Successful Installation: Explains that the wsl command being runnable does not mean Linux can be successfully installed.
3. Installation Failure Troubleshooting: How to check and fix it when installation still fails after configuration.

1. Setup & Config WSL

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

1.1 Check System Requirements

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

• Windows 10: Version 1903 or later, with Build 18362 or higher.
• Windows 11: All versions are supported.

IMPORTANT

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

1.2 Enable Hardware Virtualization

WSL 2 runs on virtualization technology, so Virtualization Technology must be enabled in your motherboard's BIOS/UEFI.

• How to check: Open "Task Manager" → "Performance" tab → "CPU".
• Check the status: Confirm that "Virtualization" in the lower-right corner shows "Enabled".
• How to enable: If it is not enabled, restart your computer, enter the BIOS/UEFI settings, find an option similar to Intel VT-x or AMD-V, and set it to Enabled.

1.3 Enable Windows Features

You need to enable the "Windows Subsystem for Linux" and "Virtual Machine Platform" features on Windows.

Method A: Via GUI (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: Via Command Line (Administrator)

Run PowerShell as Administrator and execute the following commands:

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

# Enable 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 you cannot use the Store, you can download the latest .msixbundle or .msi installer from WSL GitHub Releases for an offline installation.

1.5 Set WSL 2 as the Default Version

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

wsl --set-default-version 2

1.6 FAQ

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

2. Command Availability Does Not Equal a Successful Installation

Commands such as wsl --version and wsl -l -v running normally does not mean the conditions for installing Linux are already in place. The two are at different stages and cannot be equated.

Command availability only means:

• ✅ The WSL components are enabled/installed on Windows
• ✅ The wsl.exe command-line tool is available
• ✅ The system can recognize WSL-related commands

But successfully installing a Linux distribution requires additional conditions to be met. Common places where you may get stuck include:

1. Virtualization is turned off: VT-x / AMD-V is not enabled in BIOS/UEFI, so WSL 2 cannot start, or a virtualization error is reported when installing a distribution (see 1.2 Enable Hardware Virtualization for how to check).
2. Windows version/build is too old: WSL 2 has requirements for the kernel and version; the Home edition and overly old enterprise images may lack features (see 1.1 Check System Requirements for how to check).
3. No Linux distribution has actually been installed: wsl -l -v only lists installed distributions; if nothing is installed, the list is simply empty — it does not mean you can directly run Ubuntu.
4. Network / Microsoft Store issues: wsl --install -d <Distro> needs to pull the image from the Store or the network; corporate networks, proxies, and firewalls may all block it.
5. Insufficient permissions: Installing a distribution or modifying WSL settings requires administrator privileges.

TIP

To put it simply: WSL commands working ≠ Linux is ready — you've only got the "ticket" to the venue, but the system hasn't actually been installed yet.

3. Installation Failure Troubleshooting

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

3.1 Run the "One-Click Check" First

Run PowerShell as Administrator and execute the following in order:

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

• ✅ If both commands run smoothly, the WSL optional components are enabled and the virtualization requirements are basically met.
• ❌ If they fail, the error will directly indicate what is missing (e.g., Virtual Machine Platform, Hyper-V, BIOS virtualization, etc.).

Then run systeminfo and confirm that Virtualization Enabled In Firmware: Yes appears in the output. If none of the above reports an error, you can safely run wsl --install to install a distribution.

NOTE

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

3.2 Manual Verification Checklist

If the "one-click check" still cannot pinpoint the problem, check the items one by one:

1. Check whether BIOS/firmware virtualization is enabled: Run systeminfo in an administrator PowerShell; 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

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

3.3 Common Failure Causes at a Glance

Situation	Explanation	How to handle
Virtualization not enabled in BIOS	Always fails	Restart and enable VT-x / AMD-V in the BIOS (see 1.2)
Windows 10 below 19041	wsl --install not supported	Upgrade the system (see 1.1)
Hyper-V / virtualization disabled in an enterprise environment	May fail	Contact your system administrator
Old Home edition system	Manual installation required	Manually install the WSL kernel following 1.4

3.4 Error 0xc03a0014: Virtual Disk Support Provider Missing

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, but Windows' VHD/VHDX virtual disk stack is not working properly, causing WSL 2 to fail when registering a distribution or creating/mounting ext4.vhdx.

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

Check and fix the issue in the following order:

1. The 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 Windows Features, and then you must restart. Windows Home edition does not have full Hyper-V, but WSL 2 only needs the 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 they are missing, you can add them manually via hdwwiz.exe (Storage controllers → Microsoft → Microsoft VHD Loopback Controller), and make sure the FsDepends service is not disabled.

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

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

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

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

TIP

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