Wsl Installdistro Service Registerdistro Createvm Hcs Hcs_e_hyperv_not_installed

When you run wsl --install or wsl --install -d <distro>, the Install-WindowsOptionalFeature pipeline eventually calls the internal InstallDistribution service, which in turn invokes RegisterDistribution and CreateVM against the Host Compute Service (HCS), and a failure such as hcs_e_hyperv_not_installed means the host Hyper-V role or virtual machine platform are not enabled or not running on this machine.

What the InstallDistribution Service Actually Does

The InstallDistribution service is the bridge between the Windows package manager and the low-level WSL bootstrapper. When you ask for a new distro, this service prepares the filesystem, registers metadata, and ensures that the distro can be listed and launched by the WSL control service. Behind the scenes, it calls RegisterDistribution to add the distro to the system registry used by the WSL shim, and it prepares the necessary network and security objects so the VM can start cleanly. If any step in this flow fails early, you may never get to the point where you see your distro on the desktop or in wsl -l.

Under the hood, the service also coordinates with the Host Compute Service (HCS), which is the modern API layer that manages isolated compute containers and virtual machines on Windows. The HCS is responsible for creating the lightweight VM that hosts the Linux kernel and the distro rootfs. If the HCS cannot create the VM because Hyper-V is not present or not enabled, the operation aborts and you may encounter errors that reference hcs_e_hyperv_not_installed or similar HRESULTs. Understanding this chain helps you see why enabling the right Windows features is mandatory before distro creation can succeed.

How RegisterDistribution Fits Into the Workflow

RegisterDistribution is the step that writes the distro configuration into the WSL metadata store, typically under %ProgramData%\wsl\config on newer Windows builds. This registration includes the kernel command line, the path to the rootfs, networking settings, and the launch flags that tell the WSL shim how to start the VM. If this registration is incomplete or corrupted, you may see errors when you try to launch the distro, even though the filesystem itself is intact. Tools like wsl --list --verbose read this store to report the state and WSL version of each distro.

During an online install from the Microsoft Store, RegisterDistribution is called after the package is extracted and the filesystem is laid down on your drive. It ensures that the distro GUID is unique, that the kernel and init binaries are in place, and that the default user and network settings are applied. When you use wsl --install -d <distro>, this function is invoked automatically, and if the underlying infrastructure such as Hyper-V is missing, the registration may still appear to succeed while the subsequent CreateVM step will fail with an HCS error like hcs_e_hyperv_not_installed.

What CreateVM Does and Why HCS Matters

CreateVM is the operation that asks the Host Compute Service (HCS) to spin up a virtual machine instance for the distro. This includes creating the virtual compute context, attaching the VHD or ext4 filesystem, setting up the virtual NIC, and preparing the process that will eventually launch wsl.exe as a host process. The HCS is the engine that isolates the kernel and provides the lightweight virtualization boundary used by WSL 2. Without a functional HCS, no WSL 2 distro can start, and attempts to launch one will return errors that bubble up from the host virtualization layer.

The HCS is implemented as a Windows service that relies on the Hyper-V virtualization stack, even if you never explicitly install the full Hyper-V role for server workloads. On client editions of Windows, this is provided by the Virtual Machine Platform optional feature, which brings in the necessary components without exposing the full Hyper-V management tools. If this feature is disabled or not installed, the HCS cannot create virtual machines, and calls to CreateVM will fail with an HRESULT such as hcs_e_hyperv_not_installed. This is why enabling Virtual Machine Platform is a common troubleshooting step before switching a distro to WSL 2.

Decoding the hcs_e_hyperv_not_installed Error

The error hcs_e_hyperv_not_installed is an HCS-specific HRESULT that indicates the virtualization infrastructure required by the Host Compute Service is not available. This does not always mean that Hyper-V as a role is disabled; it can also mean that the Virtual Machine Platform optional feature is turned off, or that the Windows kernel mode virtualization components are not loaded. On systems with nested virtualization disabled in the BIOS, or on certain editions of Windows that do not include the hypervisor, this error can appear even if the user believes Hyper-V is present.

Common triggers include running Windows Home without manually enabling the required features, using a corrupted or outdated WSL kernel update, or having virtualization disabled in the firmware. You can verify the status of the required components by running dism /online /get-features /featurename:Microsoft-Hyper-V and dism /online /get-features /featurename:VirtualMachinePlatform. If either is disabled, you must enable them with dism /online /enable-feature /featurename:Microsoft-Hyper-V /all /norestart and a similar command for the Virtual Machine Platform, followed by a reboot to ensure the hypervisor loads properly.

Correcting the Flow with Proper Prerequisites

Before you retry wsl --install or wsl --install -d <distro>, ensure that the prerequisite Windows features are enabled and that your system meets the requirements for WSL 2. This includes the Hyper-V platform, the Virtual Machine Platform optional feature, and the Linux kernel update package. On Windows 10 versions 2004 and later, or Windows 11, the flow is smoother because the kernel update is downloaded automatically, but the features still must be turned on.

To avoid repeated hcs_e_hyperv_not_installed errors, follow this checklist: first enable Virtual Machine Platform and Hyper-V via Optional Features or DISM; second, ensure your distro is set to WSL 2 with wsl --set-version <distro> 2; third, update the WSL kernel via the Microsoft Store or manual download; and fourth, reboot to让 the hypervisor initialize. Once these prerequisites are satisfied, InstallDistribution, RegisterDistribution, and CreateVM will complete without raising the HCS error, and your distro will launch as expected.

Conclusion

Understanding the relationship between wsl --install, the InstallDistribution service, RegisterDistribution, CreateVM, and the Host Compute Service clarifies why prerequisites like Hyper-V and Virtual Machine Platform are non-negotiable for WSL 2. A clear grasp of this pipeline helps you troubleshoot errors such as hcs_e_hyperv_not_installed more effectively, ensuring that your distro moves from registration to VM creation without interruption. With the features enabled and the kernel updated, you can rely on the integration between these components to deliver a smooth WSL installation experience.