Windows Subsystem for Linux 2

Master WSL on Windows 11 for fast, flexible development

This deep dive explains how to install, configure, and scale WSL 2 so your workflows feel native on both Windows and Linux. Pair the stability of Windows with the power of the Linux CLI, GPU acceleration, and cloud tooling.

  • ✓Install a complete Linux userland in minutes—no dual boot, repartitioning, or complex virtualization required.
  • ✓Share files, networking, and tooling seamlessly between Windows 11 and your favorite Linux distributions.
  • ✓Accelerate AI, web, and cloud workflows with GPU, USB, and IDE integrations that feel native on both sides.
Install WSL nowExplore management commandsCompare WSL 1 vs WSL 2
Portrait of Mattias Vinberg
Explore my openSUSE configs →
Windows TerminalAdmin PowerShell
PS C:\\> wsl --install -d Ubuntu
PS C:\\> wsl --set-default-version 2
PS C:\\> wsl -l -v
user@wsl:~$ sudo apt update && sudo apt upgrade
user@wsl:~/projects$ code .

Tip: pair this workflow with the .wslconfig file to fine-tune CPU, memory, and swap for laptops and dev workstations.

Why WSL 2 is a powerhouse for developers

WSL bridges Windows and Linux so you can choose the best tool for each job without leaving your flow. These pillars show how it balances fidelity, convenience, and governance for modern teams.

Linux-first fidelity

WSL 2 runs a Microsoft-maintained Linux kernel in a lightweight utility VM for near-native performance.

  • Full system call support means Docker, Podman, Kubernetes, and build tools behave exactly as they do on bare metal.
  • Kernel updates are delivered through Windows Update, giving you the latest security patches automatically.

Tight Windows integration

Mix Windows productivity with Linux command-line prowess.

  • Access your Windows filesystem at /mnt/c while keeping Linux performance for large projects in /home.
  • Launch Linux binaries from PowerShell and Windows apps from Bash with shared environment variables.

Graphics & device support

WSLg and forwarders bridge hardware capabilities between environments.

  • Run GUI apps like GNOME Builder, DataGrip, or Firefox with GPU acceleration directly from WSL.
  • Attach USB devices, serial ports, and GPUs using wsl --mount and the latest CUDA/DirectML drivers.

Security & governance

Keep your dev boxes compliant without sacrificing speed.

  • Isolate projects per distro, disable interop when you need stricter boundaries, and script teardown with one command.
  • Use Microsoft Defender for Endpoint and Windows sandboxing features alongside Linux security tooling.

Choose the right Linux distro for WSL

Each distribution balances release cadence, package availability, and administrative tooling differently. Start with the profile that aligns with your workloads, then branch out for specialized stacks.

Ubuntu LTS

APT

Canonical-supported distro with predictable releases and the richest community docs.

Best for: Teams that want stability, long-term support (5 years), and easy access to PPAs for language stacks.

  • Enable the Partner repository when you need proprietary fonts or codecs.
  • Use sudo apt install ubuntu-wsl to grab curated defaults tuned for WSL.
Tip: pair distro exports (wsl --export) with your dotfiles repo for reproducible environments.

Debian Stable

APT

Minimalist base with conservative updates and rock-solid reliability.

Best for: CI agents, automation scripts, or developers who value minimal changes between updates.

  • Add backports when you need newer toolchains such as GCC or Clang.
  • Pair with direnv and asdf to keep per-project tool versions isolated.
Tip: pair distro exports (wsl --export) with your dotfiles repo for reproducible environments.

Fedora Kinoite / Workstation

DNF

Leading-edge GNOME experience with SELinux and a fast cadence.

Best for: Frontier developers testing new compilers, GNOME tooling, or Wayland-first workflows.

  • Install sudo dnf groupinstall "Development Tools" for build essentials.
  • Use rpm-ostree for immutable deployments or when layering packages over Kinoite.
Tip: pair distro exports (wsl --export) with your dotfiles repo for reproducible environments.

openSUSE Leap / Tumbleweed

Zypper

YaST-powered control with both rolling and regular release options.

Best for: Ops teams that need Btrfs snapshots, transactional updates, and granular system administration.

  • Pattern-based installs (sudo zypper in -t pattern devel_basis) accelerate language bootstrapping.
  • Use snapper to snapshot before major changes; combine with wsl --export for belt-and-suspenders backups.
Tip: pair distro exports (wsl --export) with your dotfiles repo for reproducible environments.

Install and configure WSL 2 step by step

Follow these steps to provision WSL 2 cleanly. Each command is safe to rerun and can be automated across organizations.

1

Enable required features

From an elevated PowerShell session, turn on virtualization and the Windows Subsystem for Linux components, then restart.

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

Install WSL with your preferred distro

Use the simplified installer to download the kernel, set WSL 2 as default, and grab Ubuntu, Debian, or another image in one go.

PowerShell
wsl --install -d Ubuntu
3

Stay updated and tuned

Apply the latest kernel and set WSL 2 as your default version so new distros use the performant virtualization stack.

PowerShell
wsl --update wsl --set-default-version 2
4

Bootstrap the distro

Complete the Linux user setup, refresh packages, and install essential tooling from inside the distribution shell.

PowerShell
sudo apt update && sudo apt upgrade && sudo apt install build-essential git curl unzip

Need a visual walkthrough? Jump to the installation guide for screenshots and hardware prerequisites.

Manage distros like a pro

The wsl.exe CLI controls the lifecycle of each distribution. Combine these commands with scripts to keep projects tidy and reproducible.

wsl -l -v

List installed distributions with their version (WSL 1 or WSL 2) and current state.

wsl --set-version Ubuntu-24.04 2

Convert a distro to WSL 2 when you need full system call compatibility and better file I/O.

wsl --set-default Ubuntu-24.04

Choose the distribution that launches when you type wsl in Windows Terminal.

wsl --export Debian debian-backup.tar

Capture a snapshot you can version, store off-machine, or restore with wsl --import.

wsl --terminate Ubuntu-24.04

Gracefully shut down a running distro before freeing disk space or resizing the virtual disk.

Daily Linux operations playbook

Keep your distributions healthy with a predictable maintenance rhythm. Standardize package manager commands so teammates and automation know exactly what to run.

Ubuntu / Debian

Package manager: APT

Shell
# Update
sudo apt update && sudo apt upgrade
# Search
apt search <package>
# Install
sudo apt install <package>
# Cleanup
sudo apt autoremove && sudo apt clean

Fedora

Package manager: DNF

Shell
# Update
sudo dnf upgrade --refresh
# Search
dnf search <package>
# Install
sudo dnf install <package>
# Cleanup
sudo dnf autoremove

openSUSE

Package manager: Zypper

Shell
# Update
sudo zypper refresh && sudo zypper update
# Search
zypper search <package>
# Install
sudo zypper install <package>
# Cleanup
sudo zypper packages --orphaned

Store these commands in a shared README.md or onboarding script so every new hire understands the expected hygiene tasks.

Desktop environments in WSLg

WSLg brings full Linux GUI support. These desktop recipes give you a polished workstation without leaving Windows. Pick the one that matches your workflow and hardware budget.

Ubuntu Desktop (GNOME)

Full GNOME Shell experience with WSLg support for windowed apps.

WSLg ready
  1. sudo apt install ubuntu-desktop --no-install-recommends
  2. wsl --shutdown to restart the subsystem with new systemd targets.
  3. Use systemctl --user enable --now gnome-keyring-daemon.service for credential prompts.

KDE Plasma

Highly customizable Qt-based desktop, great for multi-monitor productivity.

WSLg ready
  1. sudo apt install kde-plasma-desktop or sudo dnf groupinstall "KDE Plasma Workspaces"
  2. Install xdg-desktop-portal-kde to improve file dialogs and clipboard bridging.
  3. Set the QT_QPA_PLATFORMTHEME=qt5ct environment variable if theming looks inconsistent.

Xfce minimal desktop

Lightweight alternative for resource-constrained machines.

WSLg ready
  1. sudo apt install xubuntu-desktop --no-install-recommends
  2. Disable screen lockers (light-locker-command -a) to avoid blank resume screens inside WSLg.
  3. Map Super key shortcuts via xfconf-query for quick launchers alongside Windows hotkeys.

Heads up: heavy desktop sessions can increase VRAM usage. Use wsl --shutdown after long GUI sessions to reclaim resources.

Integrate WSL with your tooling

WSL thrives when you pair it with modern editors, container runtimes, and automation workflows. Start with these integration patterns and tailor them to your stack.

Editor & IDE workflow

  • Use VS Code with the Remote - WSL extension for Linux terminals, debugging, and IntelliSense from Windows.
  • Neovim, JetBrains Gateway, and Fleet all support remote targets that point at your WSL workspace.

Container & cloud tooling

  • Docker Desktop integrates with WSL 2 backends, letting Linux containers share the Windows networking stack.
  • Podman, nerdctl, and kind work inside WSL with native cgroups and overlayfs support.

Graphics, AI, and data

  • Access GPUs via NVIDIA CUDA on WSL, AMD ROCm, or DirectML for machine learning workloads.
  • Run Jupyter, VS Code notebooks, or data visualization apps with hardware acceleration through WSLg.

Operational excellence

  • Forward ports to Windows with wsl --port, or expose services to the LAN by binding to 0.0.0.0 inside the distro.
  • Use Windows Task Scheduler or GitHub Actions runners to orchestrate scripts that target WSL environments.

Performance tuning & reliability

Optimize file placement

Keep active project files on the Linux side (~/projects) for the best git, npm, and compile speeds. Use /mnt/c only for quick asset sharing or when Windows-only tooling must access the data.

Control resource usage

Create a .wslconfig in your Windows user profile to pin CPU, memory, and swap allocations. This prevents runaway processes and keeps laptops cool during long builds.

Mindful shutdowns

Use wsl --shutdown or Windows Terminal’s “Close all tabs” to flush disks cleanly. Combine with bcdedit /set hypervisorlaunchtype off when you need to temporarily disable virtualization.

Automate everything

Treat WSL environments as disposable, reproducible dev shells. Automation keeps everyone aligned, whether you manage a team or personal projects.

One-command onboarding

  • Publish a PowerShell profile snippet that installs WSL, your preferred distro image, configures git, and seeds dotfiles.
  • Pair with cloud-init or Ansible inside the distro to bootstrap languages, SSH keys, and secrets managers.

Store Bootstrap scripts in a public GitHub Gist and reference them from your team handbook.

Scheduled maintenance

  • Use schtasks or PowerShell scheduled jobs to run wsl --update nightly and apply apt security patches.
  • Automate wsl --export backups to OneDrive, Azure Files, or an external disk for disaster recovery.

Tag exports with timestamps (wsl --export Ubuntu backup-%DATE%.tar) for simple retention policies.

Compliance & hardening

  • Disable interop via /etc/wsl.conf (set interop=false) when policy requires strict separation between Windows and Linux.
  • Mount encrypted VHDX files for sensitive projects and wipe them with wsl --unregister when the engagement ends.

Document the hardening checklist in your security wiki and version it alongside infrastructure-as-code.

Troubleshoot Linux behavior

When the Linux side of WSL misbehaves, use these diagnostics before rebuilding a distro. They capture the most common cross-OS friction points.

Systemd not starting?

Make sure your distro has systemd enabled in /etc/wsl.conf and that you are on WSL 2.

  • Add [boot] systemd=true to /etc/wsl.conf and restart with wsl --shutdown.
  • Verify with systemctl list-units --type=target --state=running.

Clock skew between Windows and Linux

Occasional suspend/resume cycles can desync the hardware clock inside the VM.

  • Run sudo hwclock --hctosys or use timedatectl set-ntp true.
  • Schedule wsl.exe --shutdown on resume events via Task Scheduler for clean sync.

High disk usage in ext4.vhdx

Large node_modules or Docker layers can bloat the virtual disk.

  • Use sudo du -sh /* to spot growth hotspots.
  • Compact the disk from Windows: wsl --shutdown && diskpart > select vdisk file=C:\Users\<you>\AppData\Local\Packages\...\ext4.vhdx > compact vdisk.

Slow filesystem access from /mnt/c

NTFS passthrough is convenient but slower for many small files.

  • Clone repos into ~/projects and use git config --global core.autocrlf input.
  • Leverage [automount] options in /etc/wsl.conf to disable metadata translation when not required.

Frequently asked questions

Can I run systemd services automatically?

Yes. Enable systemd in /etc/wsl.conf, then use systemctl --user enable for per-user timers or systemctl enable for global services. WSL 2 honors dependencies on boot.

How do I share SSH keys securely?

Store keys in your Windows profile, then use ln -s /mnt/c/Users/<you>/.ssh ~/.ssh with chmod 600 permissions inside WSL. Consider Windows Hello backed FIDO2 keys for hardware security.

Is Docker Desktop required?

Not strictly. Native Docker Engine on WSL works with dockerd-rootless-setuptool.sh or dockerd, but Docker Desktop simplifies updates, networking, and credential helpers.