Installing WSL (Windows Subsystem for Linux) on Amazon WorkSpaces
In Post 1 we enabled nested virtualization on Amazon WorkSpaces, and in Post 2 we automated that enablement at scale with Lambda and S3. Now let's put it to work.t
One of the most common reasons developers ask for nested virtualization is WSL — the Windows Subsystem for Linux. WSL lets a WorkSpace run a real Linux kernel and full distributions (Ubuntu, Debian, and others) directly inside Windows, so developers get native Linux tooling, containers, and shells without leaving their virtual desktop.
This post walks through installing and verifying WSL on an Amazon WorkSpace, from prerequisites through your first Linux shell, plus the troubleshooting you're most likely to hit.
Note: WSL 2 relies on a lightweight virtual machine. On Amazon WorkSpaces that requires nested virtualization to be enabled first — this is the step that makes WSL 2 possible on a virtual desktop.
Before you start: prerequisites
WSL on a WorkSpace has a hard dependency chain. Work through these in order.
Required
- The workspace must have been restarted after enabling so the change is active.
- A Power or higher bundle (4+ vCPU recommended) on a supported OS — Windows Server 2019/2022/2025 or Windows 11. WSL 2 will not run on the bundles and operating systems excluded from nested virtualization (see the limitations section in Post 1).
- Administrator rights inside the WorkSpace (WSL installation modifies Windows features).
- Internet access from the WorkSpace to download the kernel and a Linux distribution.
- Confirm nested virtualization is active first
From inside the WorkSpace, open PowerShell as Administrator and confirm the virtualization platform is available:
# Should report State : Enabled for the Virtual Machine Platform featureGet-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform | Select-Object FeatureName, StateIf this shows
Disabled , nested virtualization isn't active yet — revisit Post 1/Post 2 and make sure the WorkSpace was restarted after enabling.
Option 1: Install WSL with a single command (recommended)
On current Windows builds,
wsl.exe can install everything — the required Windows features, the WSL 2 kernel, and a default Ubuntu distribution — in one step.- Inside the WorkSpace, open PowerShell or Windows Terminal as Administrator.
- Run the install command:
wsl --install- This enables the Windows Subsystem for Linux and Virtual Machine Platform features, downloads the latest WSL 2 Linux kernel, sets WSL 2 as the default, and installs Ubuntu as the default distribution.
- When prompted, restart the WorkSpace. Because WSL turns on Windows optional features, a reboot is required to finish setup.
- After the WorkSpace returns to AVAILABLE and you reconnect, the Ubuntu setup will continue automatically (or launch Ubuntu from the Start menu). Create your Linux username and password when prompted.

- That's it — you now have a working WSL 2 environment.
Install a specific distribution
To pick a distribution instead of the Ubuntu default, list what's available and install by name:
# List distributions available to installwsl --list --online
# Install a specific one (example: Debian)wsl --install -d Debian
Option 2: Manual / step-by-step install
Use this path if
wsl --install is blocked by policy, the WorkSpace image is older, or you want explicit control over each component.- Open PowerShell as Administrator and enable the two required Windows features:
# Enable the Windows Subsystem for Linuxdism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# Enable the Virtual Machine Platform (needed for WSL 2)dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart- Restart the WorkSpace so the features take effect.
- Download and install the WSL 2 kernel update package from Microsoft (
wsl_update_x64.msi), then set WSL 2 as the default version:
# Set WSL 2 as the default versionwsl --set-default-version 2- Install a distribution — from the Microsoft Store (search for "Ubuntu") or from the command line:
# Install a distributionwsl --install -d Ubuntu- Launch the distribution and complete the Linux username/password setup.
Verifying the installation
Confirm WSL is installed, running version 2, and that your distribution is registered.
# Show WSL version, kernel version, and default distrowsl --version
# List installed distributions and which WSL version each useswsl --list --verboseExample output:
NAME STATE VERSION* Ubuntu Running 2The
VERSION column should read 2. Then drop into the Linux shell and verify the kernel:# Launch the default distrowsl
# Inside the Linux shell:uname -aExample Linux output:
Linux WORKSPACE 5.15.x-microsoft-standard-WSL2 #1 SMP ... x86_64 GNU/LinuxThe
microsoft-standard-WSL2 kernel string confirms you're running the WSL 2 virtual machine — which is only possible because nested virtualization is active on the WorkSpace
Troubleshooting
Symptom | Cause | Fix |
|---|---|---|
WslRegisterDistribution failed with error: 0x80370102 | Virtualization not available to the WorkSpace | Nested virtualization isn't enabled/active. Verify with Get-WindowsOptionalFeature ... VirtualMachinePlatform and confirm the WorkSpace was restarted after enabling (Post 1/Post 2). |
Please enable the Virtual Machine Platform Windows feature | VM Platform feature off | Run the dism.exe ... VirtualMachinePlatform command in Option 2, then restart. |
wsl --install not recognized | Older Windows build | Use the manual steps in Option 2, or update Windows on the WorkSpace image. |
Distro launches but stays on VERSION 1 | WSL 2 not set as default | Run wsl --set-default-version 2, then wsl --set-version <Distro> 2. |
No internet / download fails | WorkSpace network egress restricted | Ensure the WorkSpace subnet/security group and any proxy allow outbound HTTPS to Microsoft endpoints. |
Slow resume / lost state after AutoStop | AutoStop + nested virt reboot behavior | On Windows Server 2025 / Windows 11 24H2/25H2, AutoStop performs a full reboot. Use AlwaysOn running mode for persistent WSL sessions (see Post 1 limitations). |
Verify from the WorkSpaces side
If WSL 2 refuses to start, double-check nested virtualization at the WorkSpace property level (from an admin machine with the AWS CLI):
aws workspaces describe-workspaces \ --workspace-ids ws-xxxxxxxxx \ --region us-east-1 \ --query "Workspaces[0].WorkspaceProperties.NestedVirtualizationEnabled"If this returns
false or null , enable it using the method from Post 1 or Post 2 and restart the WorkSpace before retrying WSL.
Everyday WSL commands
A few commands you'll use often once WSL is running:
# Shut down all running distributions (frees the WSL VM)wsl --shutdown
# Set a default distributionwsl --set-default Ubuntu
# Run a single Linux command without opening a full shellwsl echo "Hello from Linux"
# Update the WSL kernelwsl --update
Summary
- WSL 2 on Amazon WorkSpaces depends on nested virtualization being enabled and active — enable it first via Post 1 (manual) or Post 2 (automated), and restart the WorkSpace.
- The fastest install is a single
wsl --installfrom an elevated shell, followed by a restart; a manual DISM-based path is available when needed.
- Verify with
wsl --list --verbose(should show VERSION 2) and themicrosoft-standard-WSL2kernel string fromuname -a.
- The most common failure —
0x80370102— almost always means nested virtualization isn't active yet, so start troubleshooting there.
This completes the three-part series:
- Post 3 - Installing WSL, the payoff for developers (this post)
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article