Unable to Install, Update WSL2 within Virtual Desktop - No Network - Azure Virtual Desktop

WSL2 installation failures in Azure Virtual Desktop stem from missing network connectivity required for component downloads. You can resolve this by manually downloading the kernel update package and MSI installer on a connected machine, then transferring them to the AVD session via USB or shared storage to complete the offline setup.

Understanding the Offline Constraint

Azure Virtual Desktop (AVD) environments are often configured with strict security policies that restrict outbound internet access. When you attempt to run wsl --install or update WSL2 within such an isolated session, the command fails because it cannot reach Microsoft’s update servers. Unlike standard Windows updates which may cache components, the WSL2 Linux kernel and distribution packages require fresh downloads during initial installation or major version upgrades. It is crucial to understand that WSL2 does not inherently fail due to proxy settings if the system proxy is correctly configured. The issue here is specifically the absence of any network path to the download source. Attempting to troubleshoot proxy configurations first will waste time if the virtual network simply blocks all external traffic. The solution requires shifting from an online automated install to a manual offline deployment strategy.

Prerequisites for Offline Installation

Before proceeding, you must prepare the necessary files on a separate machine that has unrestricted internet access. This machine should ideally be running a similar version of Windows 10 or 11 to ensure compatibility with your AVD hosts. You will need two primary components: the Linux kernel update package and the WSL2 Windows Installer package. The Linux kernel update provides the hypervisor driver and kernel binaries required to run the Linux subsystem. The WSL2 installer package contains the necessary registry keys and system components to enable the feature. Downloading these ensures that the AVD session can install WSL2 without attempting to fetch data from the internet.

Step-by-Step Manual Installation Guide

Follow these steps to perform the installation entirely within the disconnected AVD environment.

1. Download Components: On your connected machine, visit the official GitHub repository for the WSL kernel updates. Download the latest .msi file for the Linux kernel. Additionally, download the WSL2 Windows Installer package from the Microsoft Store or the official documentation page.
2. Transfer Files: Move both downloaded files to a portable drive, such as a USB stick, or upload them to a secure internal file share accessible by the AVD session. Ensure the transfer method complies with your organization's data loss prevention policies.
3. Enable WSL Feature: Log into your Azure Virtual Desktop session. Open PowerShell as an Administrator. Run the following command to enable the necessary Windows features:

   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

   Restart the virtual machine if prompted.
4. Install Kernel Update: Navigate to the folder containing the transferred files. Double-click the Linux kernel update .msi file. Follow the prompts to install the package. This registers the hypervisor drivers locally.
5. Install WSL2: After the kernel update completes, double-click the WSL2 installer .msi file. This sets WSL2 as the default version for new distributions.
6. Verify Installation: Open a new Command Prompt or PowerShell window and run wsl --list --verbose. If no errors appear, the installation was successful.

This method bypasses the network dependency entirely. By pre-fetching the binaries, you eliminate the timeout errors that typically plague offline installations. For users who need to manage files between the Windows host and the Linux guest after installation, refer to our guide on Access Linux Files from Windows Side with WSL2: A Tech Support Guide to optimize file sharing performance.

Troubleshooting Common Errors

Even with offline files, certain configuration issues may arise. If the installation fails at the kernel stage, ensure that Hyper-V or the Windows Hypervisor Platform is enabled in your BIOS or UEFI settings. Some AVD images disable hardware virtualization by default for performance reasons, which will prevent WSL2 from loading. If the command wsl --set-default-version 2 returns an error, check your Windows build number. Older builds of Windows 10 require specific updates before they support WSL2. In such cases, you may need to apply cumulative updates via Windows Update on a connected machine and transfer those update packages offline as well. Another common symptom is the "WSL2 not installed" message despite completing the steps above. This usually indicates that the system reboot did not fully register the new hypervisor drivers. Perform a hard restart of the AVD session rather than just logging off and back on. This forces the kernel to reload the newly installed drivers. For further details on integrating WSL2 with your existing Windows environment, including network connectivity setups once you have a connection, see Connecting to TCP WSL2 on Windows: A Comprehensive Guide.

Frequently Asked Questions

Can I use a proxy server to fix the offline installation?

No, a proxy server requires an active network connection to route traffic. If your AVD session has no internet access, configuring a proxy will not allow the system to download the WSL2 kernel or installer packages. You must use the offline manual installation method described above.

Does WSL2 work on older versions of Windows 10?

WSL2 requires Windows 10 version 1903 or higher with build 18362 or later. If your AVD image runs an older build, you must update the operating system first. Without a valid OS build, the WSL2 feature cannot be enabled regardless of whether you have the installer files.

How do I know if my AVD supports hardware virtualization?

You can check by opening Device Manager and looking for "Hyper-V" under System devices. If it is missing, your AVD host may not have virtualization enabled. Contact your Azure administrator to verify if the underlying VM type supports nested virtualization or WSL2 requirements.

Is it safe to transfer MSI files via USB?

Yes, provided you scan the files for malware before transferring them. Since the files are sourced directly from Microsoft or trusted repositories, they are generally safe. Ensure your organization’s policy allows removable media usage in the AVD environment.

What happens if I install the wrong kernel version?

Installing an incompatible kernel version may cause WSL2 to fail to start. Always match the kernel package to your Windows architecture (x64 or ARM64). Using the x64 kernel on an ARM-based AVD instance will result in immediate failure upon launching a Linux distribution.