Installing WSL 2: A Practical Engineer’s Guide

Linux tooling remains essential for modern development workflows, but context-switching between Windows and a separate Linux VM is suboptimal—resource drain, filesystem headaches, and synchronization issues abound. The Windows Subsystem for Linux (WSL), especially version 2, eliminates most logistical pain points and introduces near-native compatibility with a fraction of the overhead.

Below is a concise, tested installation procedure for WSL 2, including edge cases and common pitfalls.

Prerequisites

Note: On some corporate-managed devices, Group Policy settings may block WSL installation.

Step 1. Enable Windows Subsystem for Linux

PowerShell (preferred):

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Or via GUI (slower, not scriptable): Control Panel › Programs › Turn Windows features on or off › Windows Subsystem for Linux.

Do not skip the restart prompt. Some installation issues stem from pending reboots.

Step 2. Enable Virtual Machine Platform

Critical for WSL 2. In elevated PowerShell:

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

Again, reboot is mandatory.

Step 3. Confirm Virtualization Support

Attempting to run WSL 2 without VT-x/AMD-V enabled triggers:

WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel

or, in some environments:

Error: 0xc0351000 Virtual Machine Platform is not enabled

If this appears, enter your BIOS/UEFI and ensure "Intel VT-x" or "AMD-V" is enabled. On some Dell/Lenovo systems, these options are in "Advanced" > "Virtualization".

Step 4. Set Default to WSL 2

PowerShell:

wsl --set-default-version 2

If you receive Invalid command line option: --set-default-version, your Windows build is too old. Update via Windows Update.

Step 5. Install a Linux Distribution

Microsoft Store > Search: "Ubuntu", "Debian", "openSUSE", or "Kali Linux"

Select preferred distro. Example: Ubuntu 22.04 LTS is stable for most workloads.

Alternative (for disconnected networks):
Download .appx package and install with Add-AppxPackage.

On first launch, set up a UNIX username and password.

Step 6. Validate Installation

Check distribution(s) and WSL version mapping:

wsl -l -v

Typical output:

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

If you see VERSION 1, manually upgrade:

wsl --set-version <DistroName> 2

Replace <DistroName> with exact listed name, e.g. Ubuntu-22.04.

Side Note: Kernel Package Issues

If kernel update is required, PowerShell will prompt:

WSL 2 requires an update to its kernel component. For more information, visit https://aka.ms/wsl2kernel

Resolution:
Download and install the WSL2 kernel package.

Non-Obvious Tips

• For Docker Desktop or custom Kubernetes clusters, only WSL 2 supports systemd natively.

• Need access to Windows filesystem? Under WSL: /mnt/c/Users/...

• To export/import distros (backups, CI workflows):

  wsl --export Ubuntu-22.04 C:\backups\ubuntu.tar
  wsl --import UbuntuTest D:\wsl\test C:\backups\ubuntu.tar --version 2
  

• If you later add Hyper-V for other VMs, WSL 2 continues functioning, but heavy Hyper-V workloads may compete for memory.

Example: Deep Version Inspection

Check the WSL kernel version inside your distro:

$ uname -a
Linux DESKTOP-EXAMPLE 5.15.90.1-microsoft-standard-WSL2 #1 SMP Mon Mar 20 17:06:30 UTC 2023 x86_64 x86_64 x86_64 GNU/Linux

For distro release info:

$ lsb_release -a
Distributor ID: Ubuntu
Description:    Ubuntu 22.04.4 LTS
Release:        22.04
Codename:       jammy

Known issue: On some managed networks, Store downloads silently fail. Direct Appx install is a workaround, but Group Policy may still intervene.

Summary: With WSL 2 configured, you have a near-native Linux environment—suitable for CI/CD agents, container builds, cross-platform dev work, and more. For tightly integrated use, consider enabling systemd support (Windows 11 22H2+).

Any operational friction, check Windows Event Viewer > System and Application logs for LxssManager errors. Very rare, but saved hours of debugging in some cases.

There’s always more nuance—kernel version edge cases, filesystem perf tuning—but this guide is current as of Windows 11 23H2 and Ubuntu 22.04 LTS. Adjust as your stack evolves.