Linux on WSL2: Complete Setup Guide for Windows

Tested on: Windows 11 23H2 · Windows 10 22H2 · WSL2 with Ubuntu 26.04 LTS — Last updated: June 2026

WSL2 runs a genuine Linux kernel — built and maintained by Microsoft — directly on Windows 10 and 11, with no dual-boot partitioning and no full VM overhead. You get native Linux binaries, a real ext4 filesystem, systemd, GUI app support via WSLg, and seamless integration with Windows tooling like VS Code. This guide covers everything from first install through production-ready configuration.

Contents

WSL2 vs. Your Other Options

Before committing, understand what you're choosing:

Option	Linux kernel	Performance	GUI apps	Best for
WSL2	Real (Microsoft build)	Near-native for CLI; slower on Windows FS	Yes (WSLg)	Development on Windows
WSL1	Syscall translation layer	Better Windows FS access; no real kernel	No	Legacy or cross-filesystem workflows
VirtualBox / VMware	Real	Good with Guest Additions; RAM overhead	Full desktop	Testing full Linux desktop environments
Dual boot	Real	Bare metal — no compromise	Full desktop	Primary Linux workstation

WSL2 is the correct choice when Windows is your primary OS and you need Linux for development, containers, scripting, or running Linux-native binaries. It is not a replacement for a dedicated Linux machine doing GPU-intensive workloads or bare-metal kernel development.

Prerequisites

Windows 10 version 2004 (Build 19041) or later, or any Windows 11 release
64-bit processor with hardware virtualization enabled in BIOS/UEFI — Intel VT-x or AMD-V
At least 4 GB RAM; 8 GB or more recommended if you plan to run Docker or multiple distros
PowerShell or Windows Terminal running as Administrator for the initial install steps
An internet connection for downloading the kernel and distribution

To verify virtualization is active, open Task Manager → Performance → CPU and confirm "Virtualization: Enabled". If it shows Disabled, enter your BIOS and enable VT-x or AMD-V before continuing.

Install WSL2

One-Command Install (Recommended)

Open PowerShell as Administrator and run:

wsl --install

This single command does everything: enables the WSL Windows feature, installs the Virtual Machine Platform, downloads the latest Microsoft Linux kernel, sets WSL2 as the default version, and installs Ubuntu. Restart when prompted. After reboot, Ubuntu finishes setup automatically and prompts you for a Linux username and password.

Install a Specific Distribution

If you want Debian, Kali, or openSUSE instead of Ubuntu:

# See everything available in the Microsoft Store feed
wsl --list --online

# Sample output:
# NAME                   FRIENDLY NAME
# Ubuntu                 Ubuntu
# Debian                 Debian GNU/Linux
# kali-linux             Kali Linux Rolling
# Ubuntu-24.04           Ubuntu 26.04 LTS
# openSUSE-Tumbleweed    openSUSE Tumbleweed

# Install your preferred distro
wsl --install -d Ubuntu-24.04
wsl --install -d Debian
wsl --install -d kali-linux

# Confirm what's installed and which WSL version each uses
wsl --list --verbose

# Expected output from wsl --list --verbose:
  NAME            STATE           VERSION
* Ubuntu-24.04    Running         2
  Debian          Stopped         2

Upgrade an Existing WSL1 Distro

If you installed WSL1 previously and want to upgrade:

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

# Upgrade a specific existing distro from WSL1 to WSL2
wsl --set-version Ubuntu 2

# This can take a few minutes — it converts the filesystem in place
# Verify the result
wsl --list --verbose

First Login and System Setup

After the restart, Ubuntu opens and asks for a UNIX username and password. This is an independent Linux account — it does not need to match your Windows credentials. This user is automatically added to sudo.

# Update all packages before doing anything else
sudo apt update && sudo apt upgrade -y

# Install a practical base set of tools
sudo apt install -y curl wget git vim build-essential unzip jq tree htop

# Confirm you're running a real Linux kernel
uname -r
# 5.15.167.4-microsoft-standard-WSL2

# Check your distro version
lsb_release -a
# Distributor ID: Ubuntu
# Release:        24.04
# Codename:       noble

Filesystem Layout and Cross-OS File Access

Accessing Windows Files from WSL2

All Windows drives are mounted automatically under /mnt/:

# List your C: drive root
ls /mnt/c/

# Navigate to your Windows user profile
cd /mnt/c/Users/YourWindowsUsername/

# Copy a file from Windows into your WSL home directory
cp /mnt/c/Users/YourWindowsUsername/notes.txt ~/

# Open a Windows project folder in VS Code from WSL
cd /mnt/c/Projects/myapp
code .

Critical performance note: I/O across the Windows/Linux filesystem boundary is slow. /mnt/c/ calls go through a translation layer. For any project you're actively compiling or running — Node.js, Python, Go, Rust — keep the source files inside the WSL filesystem at ~/projects/, not in /mnt/c/. The difference can be an order of magnitude in build times.

Accessing WSL2 Files from Windows

In Windows Explorer, type wsl.localhost in the address bar to browse all your WSL distros. The path to your home directory is wsl.localhostUbuntu-24.04homeyourusername. Pin it to Quick Access for convenience.

From inside WSL, you can open any directory in File Explorer directly:

# Open current WSL directory in Windows Explorer
explorer.exe .

# Open your WSL home directory from a WSL terminal
explorer.exe ~

Configure WSL2 Resources

Global Resource Limits (.wslconfig)

By default WSL2 claims up to 50% of system RAM and all CPU cores. On a machine with 16 GB RAM that means 8 GB is available to WSL2 — which may be fine or excessive depending on your use case. Control it with .wslconfig in your Windows user profile directory.

Open Notepad or VS Code and create C:UsersYourWindowsUsername.wslconfig:

[wsl2]
# Hard cap on RAM usage across all WSL2 instances
memory=6GB

# Number of logical processors WSL2 can use
processors=4

# Virtual swap file size
swap=2GB
swapFile=C:Tempwsl-swap.vhdx

# Experimental: mirrored networking mode (Windows 11 22H2+)
# Makes WSL2 share the Windows network stack — localhost always works
# networkingMode=mirrored

After saving, restart WSL from PowerShell:

wsl --shutdown
# Wait 5-10 seconds, then relaunch your distro

Per-Distro Settings (wsl.conf)

Settings specific to one distro live inside WSL at /etc/wsl.conf. Edit it from your WSL terminal:

sudo nano /etc/wsl.conf

[boot]
# Enable systemd — required for systemctl, Docker Engine, snapd
systemd=true

[automount]
enabled = true
# Preserve Linux file permission metadata on Windows-mounted drives
options = "metadata"
mountFsTab = true

[network]
hostname = devbox
generateResolvConf = true

[user]
# Default Linux user on wsl launch
default = yourlinuxusername

[interop]
# Allow launching Windows executables from WSL (e.g., explorer.exe, code)
enabled = true
appendWindowsPath = true

Restart WSL after saving: run wsl --shutdown from PowerShell, then reopen your distro.

Enable systemd

WSL2 has supported systemd since September 2022. Enabling it unlocks systemctl, proper service management, snap packages, and Docker Engine without Docker Desktop:

# Add the boot section if it doesn't exist yet
sudo bash -c 'cat >> /etc/wsl.conf << EOF
[boot]
systemd=true
EOF'

Shutdown and reopen WSL, then verify:

systemctl status
# Should show the systemd tree, not an error about PID 1

VS Code Integration

VS Code's Remote - WSL extension (now bundled in the Remote Development pack) connects VS Code's full backend — language servers, linters, debuggers, the integrated terminal — into the WSL environment. Install the extension from the VS Code marketplace, then from any WSL terminal:

# Open current directory in VS Code connected to WSL
code .

# VS Code opens on Windows but:
# - The terminal is a WSL bash/zsh shell
# - Extensions run natively inside Linux
# - File paths resolve inside the WSL filesystem
# - Python, Node, Go runtimes are the Linux ones

You can also open WSL from the VS Code command palette with WSL: Connect to WSL or WSL: Connect to WSL using Distro.

Running Linux GUI Apps (WSLg)

WSLg ships with Windows 11 and recent Windows 10 insider builds. It embeds a Wayland compositor and an XWayland server inside WSL2, so Linux GUI apps render as native Windows windows — no separate X server required.

# Text editor
sudo apt install -y gedit
gedit &

# Image editor
sudo apt install -y gimp
gimp &

# Full file manager
sudo apt install -y nautilus
nautilus &

# Web browser (useful for testing headless environments)
sudo apt install -y firefox
firefox &

Launched apps appear in the Windows taskbar with a penguin overlay icon. After first launch they may also appear in the Windows Start Menu. Audio works too — PulseAudio is bridged automatically through WSLg.

Install Docker on WSL2

You have two paths: Docker Desktop for Windows (GUI, easier setup, requires license for large teams) or Docker Engine directly inside WSL2 (free, lighter, requires systemd).

Option A: Docker Engine Inside WSL2

# Requires systemd=true in /etc/wsl.conf (see above)
# Install Docker Engine using the official convenience script
curl -fsSL https://get.docker.com | sudo sh

# Add your user to the docker group to run without sudo
sudo usermod -aG docker $USER

# Apply the group change in your current session
newgrp docker

# Verify
docker run hello-world

Option B: Docker Desktop for Windows

Download Docker Desktop from docker.com and install it on Windows. In Docker Desktop settings → General, enable Use the WSL 2 based engine. In Settings → Resources → WSL Integration, enable integration for your specific distro. The docker CLI inside WSL2 then talks to the Docker Desktop daemon automatically.

Essential WSL2 Management Commands

# Launch default distro
wsl

# Launch a specific distro
wsl -d Debian

# Run a one-off Linux command from PowerShell/CMD without entering a shell
wsl ls -la /home/yourusername

# Shut down all running WSL2 instances (frees all RAM immediately)
wsl --shutdown

# Stop a single distro without shutting down others
wsl --terminate Ubuntu-24.04

# Export a distro to a .tar file — use this for backups or migrations
wsl --export Ubuntu-24.04 D:Backupsubuntu-24-04.tar

# Import a backup as a new distro instance
wsl --import Ubuntu-Dev C:WSLUbuntuDev D:Backupsubuntu-24-04.tar

# Update the WSL kernel and platform to the latest version
wsl --update

# Set a different distro as the default (opened by bare `wsl` command)
wsl --set-default Debian

# Permanently delete a distro and all its data — no confirmation prompt
wsl --unregister Ubuntu-24.04

Troubleshooting

WSL2 Consuming Excessive Memory

WSL2 aggressively caches disk reads in RAM and the balloon driver that should return memory to Windows has historically been slow. Two fixes: first, add a hard memory= cap in .wslconfig as shown above. Second, if you need to reclaim memory immediately without restarting:

# Inside WSL — drop caches
sudo sh -c 'echo 3 > /proc/sys/vm/drop_caches'

# From PowerShell — full shutdown releases all WSL2 RAM instantly
wsl --shutdown

DNS Resolution Failing Inside WSL2

This is a common issue when VPNs or corporate network policies overwrite /etc/resolv.conf. WSL2 auto-generates this file on startup, but some VPN clients clobber it:

# Check what nameserver is


Further Reading

Linux for Windows Users: Key Differences
Linux Terminal for Absolute Beginners
Linux Commands Cheat Sheet
How to Install Linux in VirtualBox


$ share:XFacebookLinkedInRedditPinterestHacker News