WSL Installation: From Vanilla Windows to Integrated Linux in Under 15 Minutes

Developers often need rapid access to both Windows and Linux tooling—whether it’s running curl with extended flags, deploying a local Kubernetes cluster with kubectl, or debugging Node.js apps natively. Traditional virtual machines add latency and resource overhead. Dual-booting disrupts workflow. WSL (Windows Subsystem for Linux) bridges this gap directly.

Pre-Installation: Validate Your Windows Environment

Not all Windows builds are equal. For reliable WSL 2 support, confirm you're running:

Check your installed version:

winver

If winver reports a lower build, stop here—OS upgrade is mandatory. Anything else creates unpredictable edge cases.

Core Steps

1. Enable Required Windows Features

PowerShell is faster and more reliable than the Control Panel GUI for enabling system features. Run as Administrator:

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

Restart immediately—Windows will not properly register these features until after a full reboot.

Known issue: On some corporate endpoints, VirtualMachinePlatform won’t enable without Group Policy edits. Check with IT if you hit errors.

2. Set WSL 2 as Default

WSL 1 is technically supported, but nearly all current projects (Docker Desktop, Minikube, VS Code Remoting) preferentially use WSL 2 for its full Linux kernel and better syscall support.

wsl --set-default-version 2

Tip: If you see "WSL 2 requires an update to its kernel component," download the manual kernel update binary from https://aka.ms/wsl2kernel.

3. Acquire and Initialize a Linux Distribution

Open Microsoft Store, select a distribution—current recommendations:

• Ubuntu 22.04 LTS (widest community support; stable baseline for enterprise)
• Debian, Kali (for security work), Fedora Remix, openSUSE

Click Install. First launch takes longer as the filesystem is de-archived and provisioned. On initial run, you’ll define a UNIX username/password for the distro. This user is not linked to your Windows account.

Enter new UNIX username: engineer
New password:
Retype new password:

4. Update the Linux Userland

Fresh WSL environments are seldom fully patched.

Update all APT packages (for Ubuntu/Debian):

sudo apt update && sudo apt full-upgrade -y

Do not skip this—outdated libc or missing build tools are a frequent frustration.

5. (Optional, Recommended) Install Windows Terminal

The default conhost-based WSL shell is workable, but lacks tabs, Unicode, or easy split panes.
Install Windows Terminal from the Microsoft Store. It autoloads your installed distros, and can mix PowerShell/CMD/Bash tabs.

Advanced Integration

• Accessing Windows files:
  All drives auto-mount under /mnt, e.g., /mnt/c/Users/<yourname>/Projects.
  Example:

  cd /mnt/c/Users/engineer/Downloads
  ls -lh
  

• Launching Windows executables from WSL:

  notepad.exe myscript.py
  explorer.exe .
  

• Improving I/O performance:
  Heavy project directories (node_modules, Docker volumes) work fastest when stored in the Linux filesystem (~/project), not under /mnt/c.

• Running GUI Linux apps:
  On Windows 11+ with WSLg, try:

  sudo apt install gedit
  gedit &
  

  No VcXsrv, no configuration. If DISPLAY-related errors, confirm Windows feature “WSLg” is active.

Troubleshooting

Error Example:

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

Core point: Most “it just doesn't work” errors relate to missing virtualization support or permissions. Confirm those first.

Real-World Notes

• Frequent context switching between Windows and Linux tools (e.g., VS Code’s “Remote – WSL” extension) requires permission alignment. File permission mismatches arise if projects are moved between /mnt/c/... and native ~.
• If you need Docker inside WSL, install Docker Desktop for Windows and enable its WSL 2 backend—not legacy Docker in WSL itself. This is less intuitive but aligns with how containers map ports and volumes on localhost.

In Summary

A minimal, modern WSL deployment streamlines cross-platform dev tasks without sacrificing performance. Invest five minutes to validate your Windows build, apply system feature toggles via PowerShell, and initialize a current Linux distribution. Most ongoing issues are solved by keeping both host (Windows) and guest (WSL kernel/distro) up to date.

For production-like parity or CI environments, consider containerizing inside WSL—not running raw services. But for day-to-day dev, this setup is fast, portable, and robust.

Questions, or odd edge cases? Drop a comment or share your config. No two setups are exactly the same—and that’s half the challenge.