Why WSL

Various CLI-based AI programming tools, like Codex, are not very good at running commands in PowerShell to edit files precisely. This is partly because they were likely trained more on Unix-like syntax, and partly because PowerShell lacks tools for precise file content manipulation. Therefore, installing WSL and then installing Codex within WSL is a better choice, and it’s also the approach recommended by OpenAI.

To understand why, we need to compare how the two environments handle files and commands.

When modifying code, an AI agent can generate commands like sed, awk, diff, and patch. These tools act like surgical scalpels, allowing for stream editing of files with precision down to the line, column, or pattern. In contrast, the standard operation in PowerShell is a “read-modify-writeback” cycle: Get-Content reads a file into memory, you modify the elements, and then Set-Content writes it back. This process is not only more cumbersome but also performs poorly with large files. The AI agent would need to expend more effort to reliably generate complex PowerShell code blocks to accomplish the same modifications.

WSL2 allows the use of the Linux kernel’s native namespace technology to create a secure sandbox. This means the AI agent can run in an isolated environment where its file access is strictly confined to the project directory, and network access can be disabled. This greatly enhances the security of automated code modification.

Error: WSL2 Not Supported

Even after enabling virtualisation in the BIOS and ticking the Hyper-V box in Windows Features as per online tutorials (which is actually unnecessary), the installation still fails. It reports that the system does not support WSL2, citing a virtualisation error and that Hyper-V is not installed.

Wsl/InstallDistro/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED

Most solutions online for this issue suggest manually checking and enabling Hyper-V via the command line, or using systeminfo to check for Hyper-V support, but none of these solved my problem.

The Invisible Hyper-V

In reality, running the wsl --install command should automatically enable Hyper-V and related components, as stated on Microsoft’s website:

The wsl --install command does the following:

  • Enables the optional WSL and Virtual Machine Platform components
  • Downloads and installs the latest Linux kernel
  • Sets WSL 2 as the default
  • Downloads and installs the Ubuntu Linux distribution

The failure might be due to some “hidden” Hyper-V features not being enabled. Even if all Hyper-V related items appear ticked in the ‘Turn Windows features on or off’ GUI, this could be misleading.

Let’s use the command line to view all features. Note that dism is case-insensitive:

dism /online /get-features

These are usually shown as enabled and correspond to the Hyper-V options you see in the GUI.

  • Microsoft-Hyper-V-All
  • Microsoft-Hyper-V
  • Microsoft-Hyper-V-Tools-All
  • Microsoft-Hyper-V-Management-PowerShell
  • Microsoft-Hyper-V-Hypervisor
  • Microsoft-Hyper-V-Services
  • Microsoft-Hyper-V-Management-Clients

However, there are two other features with ‘Hyper-V’ in their names that don’t appear in the GUI (perhaps due to a translation issue from Microsoft) nor are they enabled by the wsl --install command. These are likely the main cause of the failure.

  • HyperV-KernelInt-VirtualDevice
  • HyperV-Guest-KernelInt

Use the command line to enable these two features, and then restart your system.

dism /online /enable-feature /featurename:HyperV-KernelInt-VirtualDevice /all /norestart

dism /online /enable-feature /featurename:HyperV-Guest-KernelInt /all /norestart

After restarting, try the installation again. To avoid re-downloading the distribution (which can be very time-consuming, especially with internet conditions in mainland China), you can first run the wsl command without any arguments or wsl --status to check if the core components are working correctly. If there are no more errors, you can then proceed to install your desired distribution with wsl --install -d <DistroName>.

In Conclusion

This was a very rare issue. I had never failed to install WSL with wsl --install before, but it happened. Perhaps a future WSL update will enable these two features—which may have been introduced in a recent update—by default.

Documenting this kind of tricky problem helps me get a blog post out of it, and it might also help some other unlucky person who runs into the same installation failure. It reminds me of how, back in the day, I’d often find solutions to obscure technical problems on old internet forums.