AWS Builder Center

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

Solutions Architect - End User Computing
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
  • Nested virtualization enabled on the target WorkSpace. If you haven't done this yet, follow  Post 1  (manual) or Optional Automation enablement  Post 2  (automated at scale) first.
  • 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 feature
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform |
Select-Object FeatureName, State
If 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 install
wsl --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 Linux
dism.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 version
wsl --set-default-version 2
  • Install a distribution — from the Microsoft Store (search for "Ubuntu") or from the command line:
# Install a distribution
wsl --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 distro
wsl --version

# List installed distributions and which WSL version each uses
wsl --list --verbose
Example output:
NAME STATE VERSION
* Ubuntu Running 2
The  VERSION  column should read 2. Then drop into the Linux shell and verify the kernel:
# Launch the default distro
wsl

# Inside the Linux shell:
uname -a
Example Linux output:
Linux WORKSPACE 5.15.x-microsoft-standard-WSL2 #1 SMP ... x86_64 GNU/Linux
The  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 distribution
wsl --set-default Ubuntu

# Run a single Linux command without opening a full shell
wsl echo "Hello from Linux"

# Update the WSL kernel
wsl --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 --install  from 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 the  microsoft-standard-WSL2  kernel string from  uname -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)
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article