Modern WSL installation is normally simple. On a well-connected Windows 11 machine, a few commands can enable WSL, install the runtime, download a Linux distribution, and complete the first-run setup.
On restricted, unstable, metered, or geographically problematic networks, however, the installation can fail at a less obvious layer: the Linux distribution may already be installed while the WSL runtime itself remains incomplete or outdated.
This article describes how to distinguish those layers and recover cleanly using an offline WSL MSI.
All machine names, usernames, paths, network details, and environment-specific values are anonymized.
1. WSL Is More Than One Component
A working WSL 2 environment consists of several layers:
Windows
|
+-- Windows Subsystem for Linux optional feature
|
+-- Virtual Machine Platform
|
+-- WSL runtime
|
+-- WSL Linux kernel
|
+-- Linux distribution
|
+-- Ubuntu
+-- Debian
+-- other distributions
This distinction becomes important when installation partially succeeds.
A Linux distribution may already exist while the runtime required to start it is still missing or outdated.
2. Check the Windows Features First
The two relevant Windows features can be inspected with:
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
and:
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
If disabled, enable them without immediately rebooting:
Enable-WindowsOptionalFeature `
-Online `
-FeatureName Microsoft-Windows-Subsystem-Linux `
-All `
-NoRestart
and:
Enable-WindowsOptionalFeature `
-Online `
-FeatureName VirtualMachinePlatform `
-All `
-NoRestart
A reboot is normally required before WSL 2 can operate correctly.
3. Remote Reboots Need Planning
On a remotely administered machine, rebooting Windows can sever every control path.
Before restarting, verify how remote access returns after boot.
For example:
Remote administrator
|
v
Tunnel service
|
v
Windows SSH
If the tunnel client is normally started manually, a temporary startup mechanism may be required for a maintenance reboot.
Remote-access continuity should be solved before enabling features that require restart.
4. The Distribution Can Be Installed While WSL Still Fails
After reboot, launching Ubuntu may show a message equivalent to:
Windows Subsystem for Linux must be updated
Run: wsl.exe --update
This is an important diagnostic clue.
It means:
Ubuntu distribution installed
Windows WSL features enabled
WSL runtime insufficient
Ubuntu startup blocked by runtime requirement
Reinstalling Ubuntu at this point does not solve the actual problem.
The missing dependency is the WSL runtime.
5. Why wsl --update Can Be Problematic
The normal update path is:
wsl --update
On some networks, this can exhibit:
- very slow downloads;
- long stalls;
- intermittent disconnects;
- repeated restarts from the beginning;
- inconsistent access to Microsoft or GitHub infrastructure.
A partial download reaching a visible percentage does not necessarily imply that command-line resume functionality is available.
For a large runtime package, repeated retries may waste substantial time.
6. Separate Download Location from Installation Location
A practical solution is to download the WSL MSI from a different machine with better network connectivity.
The process becomes:
Well-connected machine
|
| download official WSL MSI
v
<WslRuntime.x64.msi>
|
| transfer
v
Target Windows machine
|
| local MSI installation
v
Working WSL runtime
The package should come from Microsoft’s official WSL release source.
Choose the architecture that matches the Windows host:
x64 -> x64 MSI
ARM64 -> ARM64 MSI
7. Version Matching Is Flexible
An important practical point is that an offline WSL MSI does not always need to match the exact version that an interrupted wsl --update operation was attempting to retrieve.
Installing a newer supported official release is normally acceptable.
Conceptually:
Updater attempted: <OLDER_WSL_VERSION>
Manual MSI: <NEWER_WSL_VERSION>
Result: valid upgrade path
The key requirements are:
- correct CPU architecture;
- official package;
- supported Windows version.
8. Install the WSL Runtime Locally
Once the MSI reaches the Windows host:
msiexec.exe /i "<WSL_MSI_PATH>"
After installation, verify:
wsl --version
A healthy result should report values for:
WSL version
Linux kernel version
WSLg version
Windows version
Then:
wsl --status
should show the default WSL generation.
For a WSL 2 environment:
Default Version: 2
9. Verify the Distribution
List installed distributions:
wsl -l -v
A healthy installation may resemble:
NAME STATE VERSION
<Ubuntu> Stopped 2
Launching it:
wsl -d <DISTRO_NAME>
should enter the Linux environment.
10. First-Run Ubuntu Provisioning
The first launch creates the Linux filesystem and requests a default UNIX account.
The username does not need to match the Windows account.
Typical flow:
Enter new UNIX username:
New password:
Retype new password:
Installation successful
Once the prompt becomes something like:
<LINUX_USER>@<WSL_HOST>:~$
the Ubuntu instance is ready.
11. Verify the Linux Environment
Useful checks include:
whoami
uname -a
cat /etc/os-release
pwd
df -h /
free -h
This confirms:
- the UNIX user;
- WSL kernel;
- distribution release;
- home-directory location;
- virtual filesystem capacity;
- available memory;
- swap.
12. WSL Filesystem Capacity Can Be Misleading
A WSL 2 filesystem may report a very large virtual capacity:
/dev/<VIRTUAL_DEVICE> <VERY_LARGE_SIZE>
This does not mean the Windows host physically has that much free storage.
WSL uses a dynamically expanding virtual disk.
Therefore:
WSL filesystem free space
!=
Windows physical free space
The actual limiting resource remains the Windows volume that stores the WSL virtual disk.
This matters enormously for data-intensive workloads.
13. Proxy Warnings Do Not Necessarily Mean Failure
When Windows uses a localhost proxy, WSL may display a warning such as:
localhost proxy configuration detected
not mirrored into WSL
NAT-mode WSL does not support localhost proxy mapping
The warning means that:
Windows localhost
and:
WSL localhost
are different network namespaces.
It does not automatically mean that WSL has no Internet connectivity.
14. Test Real Connectivity Instead of Guessing
Check external HTTPS access:
curl -I --max-time <TIMEOUT> https://github.com/
Then test the package manager:
sudo apt update
If both succeed, the network is usable even if WSL continues displaying the localhost-proxy warning.
Actual application-level connectivity is more useful than interpreting the warning in isolation.
15. Final State
A successfully recovered WSL deployment may look like:
Windows
|
+-- WSL feature enabled
+-- Virtual Machine Platform enabled
+-- WSL runtime installed from official MSI
+-- WSL 2 default
|
+-- Ubuntu
|
+-- x86-64 Linux
+-- working network
+-- apt repositories reachable
+-- normal UNIX user
The main lesson is to separate:
Windows features
WSL runtime
Linux kernel
Linux distribution
into distinct layers.
When the distribution is already installed but startup demands wsl --update, reinstalling Ubuntu is usually the wrong direction. Repairing or replacing the WSL runtime directly is faster, cleaner, and much easier to troubleshoot.