WSL2 Setup Guide: Run Linux on Windows 10 and 11

Windows Subsystem for Linux 2 (WSL2) lets you run a real Linux kernel directly on Windows, without the overhead of a traditional virtual machine. It integrates tightly with Windows — you can access your Windows files from Linux, run Linux tools from the Windows command line, and use VS Code's Remote WSL extension to edit code as if you were natively on Linux. This guide covers installation, configuration, and the most useful WSL2 workflows for developers and IT professionals.

Prerequisites

Windows 10 version 2004 or later (Build 19041+), or Windows 11 (any version)
Virtualisation enabled in BIOS/UEFI — Intel VT-x or AMD-V must be enabled
Administrator rights on the machine

Installing WSL2

On Windows 10 version 2004 and all Windows 11 versions, installation is a single command:

# Install WSL with the default distribution (Ubuntu)
wsl --install

# List available distributions before installing
wsl --list --online

# Install a specific distribution
wsl --install -d Debian
wsl --install -d kali-linux
wsl --install -d Ubuntu-24.04

After installation, restart the machine. On first launch, you will be prompted to create a Linux username and password. This is separate from your Windows credentials.

Managing WSL Distributions

# List installed distributions and their status
wsl --list --verbose

# Set WSL2 as the default version for new installs
wsl --set-default-version 2

# Convert an existing WSL1 distribution to WSL2
wsl --set-version Ubuntu 2

# Set the default distribution (used when you type wsl with no arguments)
wsl --set-default Ubuntu-24.04

# Shut down all running WSL instances
wsl --shutdown

# Terminate a specific distribution
wsl --terminate Ubuntu

Accessing Files Between Windows and Linux

WSL2 provides two-way file access between Windows and Linux:

From Linux, Access Windows Files

Windows drives are mounted under /mnt/:

# Access the Windows C: drive from WSL2
ls /mnt/c/Users/

# Navigate to your Windows Desktop from WSL2
cd /mnt/c/Users/YourName/Desktop

# Copy a file from Windows to the Linux home directory
cp /mnt/c/Users/YourName/Documents/script.py ~/

From Windows, Access Linux Files

Open File Explorer and type \wsl$ in the address bar. You will see all installed WSL distributions. You can drag and drop files, and map a network drive to \wsl$Ubuntuhomeyourusername for quick access.

Performance tip: Keep project files inside the Linux filesystem (~/projects/), not in /mnt/c/. Cross-filesystem I/O (Linux accessing Windows files) is significantly slower than native Linux filesystem operations. This is especially important for large codebases.

Running Linux Commands from Windows

# Run a single Linux command from PowerShell or CMD
wsl ls -la /home/

# Run a bash script from Windows
wsl bash /home/user/scripts/deploy.sh

# Pipe Windows output to a Linux command
ipconfig | wsl grep "IPv4"

# Pipe Linux output to a Windows command
wsl cat /etc/os-release | findstr VERSION

Configuring WSL2: .wslconfig and wsl.conf

Global Settings: .wslconfig

Create a file at C:UsersYourName.wslconfig to configure resource limits and networking:

[wsl2]
memory=8GB          # Limit WSL2 memory usage
processors=4        # Limit virtual CPU count
swap=2GB            # Swap file size
swapFile=C:\Temp\wsl-swap.vhdx

# Enable experimental networking features (Windows 11 23H2+)
networkingMode=mirrored
dnsTunneling=true
firewall=true

Per-Distribution Settings: wsl.conf

Create /etc/wsl.conf inside the Linux distribution:

[automount]
enabled = true
options = "metadata,umask=22,fmask=11"
mountFsTab = true

[network]
hostname = dev-wsl
generateResolvConf = true

[interop]
enabled = true
appendWindowsPath = true

[boot]
systemd = true

Enabling systemd = true allows you to use systemctl to manage services inside WSL2, which is essential for running databases (MySQL, PostgreSQL) or web servers (nginx, Apache) that rely on systemd for startup.

Installing a Development Stack

Once inside WSL2, you have a full Ubuntu (or Debian/etc.) environment:

# Update package lists and upgrade installed packages
sudo apt update && sudo apt upgrade -y

# Install development tools
sudo apt install -y build-essential git curl wget unzip

# Install Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

# Install Python and pip
sudo apt install -y python3 python3-pip python3-venv

# Install Docker (using Docker's official WSL2 integration via Docker Desktop)
# Or install Docker Engine directly inside WSL2:
sudo apt install -y docker.io
sudo usermod -aG docker $USER

VS Code Integration

Install the WSL extension in VS Code. Then from within your WSL2 terminal:

# Open the current directory in VS Code (from WSL2 terminal)
code .

VS Code opens on Windows but the backend (file system, terminal, extensions, language servers) runs inside WSL2. This gives you native Linux tooling with a full Windows GUI IDE.

Exporting and Importing WSL Distributions

# Export a distribution to a tar file (for backup or transfer)
wsl --export Ubuntu D:Backupsubuntu-backup.tar

# Import the distribution on another machine
wsl --import Ubuntu-Restored D:WSLUbuntu D:Backupsubuntu-backup.tar