Set Up WSL2 on Windows

Overview

WSL2 (Windows Subsystem for Linux 2) runs a real Linux kernel inside Windows. It's faster than WSL1, supports full system calls, and can run Docker natively — perfect for developers who need Linux tools without dual booting.

What You Need

Step 1: Install WSL2

The easy way (Windows 10 2004+ / Windows 11):

# Open PowerShell as Administrator and run:
wsl --install

This installs Ubuntu by default and sets WSL2 as the default version. Reboot when prompted.

Manual Installation (If Automatic Fails)

  1. Enable required features in PowerShell (Admin): 
    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  2. Reboot your machine
  3. Set WSL2 as default: 
    wsl --set-default-version 2
  4. Download and install a Linux distribution from the Microsoft Store (Ubuntu, Debian, Fedora, etc.)

Step 2: Initial Configuration

Launch your installed distro from Start Menu. You'll be prompted to:

Update the System

# Ubuntu/Debian:
sudo apt update && sudo apt upgrade -y

# Fedora:
sudo dnf update -y

# Arch:
sudo pacman -Syu

File System Access

Access Windows Files from Linux

Your Windows drives are mounted under /mnt/:

# Your C: drive files
cd /mnt/c/Users/YourName/Desktop

# D: drive (if present)
ls /mnt/d/

Access Linux Files from Windows

In File Explorer, navigate to \\wsl$\ or use the distro name directly:

# In Windows File Explorer address bar:
\\wsl$\Ubuntu\home\youruser\

Integrated Terminal (Windows Terminal)

Install Windows Terminal for a modern tabbed terminal that integrates WSL distros natively.

Networking

WSL2 Network Model

Find WSL2 IP Address

# From inside WSL2:
hostname -I

# Or:
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

Mirror Windows Network (Optional)

Add to ~/.wslconfig in your Windows user folder:

[wsl2]
networkingMode=mirrored

This makes WSL2 share the host's IP directly — useful for development servers.

Install Docker in WSL2

# Install Docker Engine directly in WSL2 (Ubuntu):
sudo apt install docker.io -y
sudo systemctl start docker

# Or use Docker Desktop with WSL2 backend:
# Download from https://docs.docker.com/desktop/install/windows-install/
# Enable "WSL 2 based engine" in settings

Run GUI Applications

WSL2 includes systemd support and can run Linux GUI apps:

Enable Systemd (Ubuntu 22.04+)

# Add to ~/.wslconfig (Windows side):
[wsl2]
systemd=true

# Restart WSL:
wsl --shutdown

X11 Forwarding

  1. Install an X server on Windows (e.g., VcXsrv or MobaXterm)
  2. In WSL2, set: export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
  3. Run GUI apps normally — they display on Windows

WSLg (Built-in, Windows 11)

Windows 11 includes WSLg — just install any GUI app and run it. No extra configuration needed.

WSL Management Commands

# List installed distros (run in PowerShell):
wsl --list --verbose

# Set default version to WSL2:
wsl --set-version Ubuntu 2

# Shutdown all WSL instances:
wsl --shutdown

# Update WSL kernel:
wsl --update

# Uninstall a distro (WARNING: deletes data):
wsl --unregister Ubuntu

Customize Your Setup

Edit WSL Config

# Inside WSL, edit /etc/wsl.conf:
[network]
generateHosts = true

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

# Restart to apply:
wsl --shutdown

Set Default User

# Launch as root or specific user:
wsl -u root
wsl -d Ubuntu-22.04

Troubleshooting