WSL2 on Windows

4 minute read

WSL2 (Windows Subsystem for Linux 2) lets you run a genuine Linux kernel directly inside Windows — no virtual machine window, no dual boot. It’s fast, deeply integrated with the Windows filesystem, and the recommended way to use Linux on Windows for development.

Prerequisites

  • Windows 10 version 2004 (build 19041) or higher
  • Windows 11 (any version)
  • Admin rights on your machine

To check your Windows version:

# Open PowerShell (Win + X → Windows PowerShell)
winver
# OR
[System.Environment]::OSVersion.Version

Step 1: Install WSL2

# Open PowerShell as Administrator (right-click → Run as Administrator)

# Install WSL with Ubuntu as the default distro (one command does everything)
wsl --install

# This command:
# 1. Enables the WSL Windows feature
# 2. Enables the Virtual Machine Platform feature
# 3. Downloads the latest Linux kernel
# 4. Sets WSL2 as default
# 5. Installs Ubuntu from the Microsoft Store

# Restart your computer when prompted

If you want a specific distro:

# List available distros
wsl --list --online
# NAME                   FRIENDLY NAME
# Ubuntu                 Ubuntu
# Ubuntu-22.04           Ubuntu 22.04 LTS
# Ubuntu-24.04           Ubuntu 24.04 LTS
# Debian                 Debian GNU/Linux
# kali-linux             Kali Linux Rolling

# Install a specific distro
wsl --install -d Ubuntu-22.04

Step 2: Initial Ubuntu Setup

After the restart, Ubuntu will open automatically and ask for:

Enter new UNIX username: yourname
New password: ••••••••
Retype new password: ••••••••

# This username is your Linux user inside WSL
# It doesn't need to match your Windows username

# Verify everything is working
uname -a
# Linux DESKTOP-ABC123 5.15.153.1-microsoft-standard-WSL2 ... Ubuntu

lsb_release -a
# Ubuntu 22.04.3 LTS

Step 3: Update Ubuntu Packages

# Always update after a fresh install
sudo apt update && sudo apt upgrade -y

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

Step 4: Navigating Windows Files from Linux

WSL2 mounts your Windows drives under /mnt/:

# Access your Windows C: drive
ls /mnt/c/
# Documents  Downloads  Program Files  Users  Windows  ...

# Navigate to your Windows home folder
cd /mnt/c/Users/YourWindowsUsername/Desktop

# Create a file on your Windows Desktop from Linux
touch hello-from-linux.txt
# The file appears on your Windows Desktop immediately

# Access the Downloads folder
ls /mnt/c/Users/YourWindowsUsername/Downloads/

Best practice: Keep your projects inside the Linux filesystem (~/projects/), not on /mnt/c/. The Linux filesystem is significantly faster for Linux operations.

# Create a projects directory in Linux home
mkdir -p ~/projects
cd ~/projects

# Linux home is at (Windows path):
# \\wsl$\Ubuntu\home\yourname
# Accessible from Windows Explorer → address bar → \\wsl$\Ubuntu

Step 5: Install VS Code with WSL2 Extension

VS Code integrates seamlessly with WSL2:

# 1. Install VS Code on Windows from:
#    https://code.visualstudio.com/

# 2. Install the WSL extension in VS Code:
#    Extensions (Ctrl+Shift+X) → search "WSL" → install "WSL" by Microsoft

# 3. Open VS Code from inside your WSL2 terminal:
cd ~/projects/myproject
code .
# VS Code opens on Windows but runs all commands inside WSL2
# You get Linux file system, Linux shell, Linux tools — inside VS Code

When VS Code is connected to WSL2, you’ll see “WSL: Ubuntu” in the bottom-left corner.

Step 6: Useful WSL2 Configuration

# Create/edit ~/.wslconfig in your Windows home directory
# C:\Users\YourName\.wslconfig

# Controls global WSL2 settings

[wsl2]
# Limit WSL2 to 4 GB RAM (default is 50% of total RAM or 8 GB)
memory=4GB

# Limit to 2 processors
processors=2

# Custom swap size
swap=2GB

# Enable localhost forwarding (usually on by default)
localhostForwarding=true

# Inside WSL2: configure default shell behaviour
# Edit ~/.bashrc or ~/.zshrc

# Add to ~/.bashrc:
export PATH="$HOME/.local/bin:$PATH"   # Local binaries
export EDITOR=vim                        # Default editor

# Useful aliases
alias ll='ls -alh'
alias gs='git status'
alias gp='git pull'

# Apply changes
source ~/.bashrc

WSL2 Commands (Run in PowerShell)

# List all installed WSL distros and their WSL version
wsl --list --verbose
#   NAME            STATE     VERSION
# * Ubuntu          Running   2
#   Ubuntu-22.04    Stopped   2

# Start a specific distro
wsl -d Ubuntu-22.04

# Stop a distro
wsl --terminate Ubuntu

# Stop all distros
wsl --shutdown

# Check WSL2 kernel version
wsl --status

# Update WSL kernel
wsl --update

# Set default distro
wsl --set-default Ubuntu-22.04

# Export (backup) a distro
wsl --export Ubuntu C:\backup\ubuntu-backup.tar

# Import (restore) a distro
wsl --import Ubuntu-restored C:\WSL\Ubuntu C:\backup\ubuntu-backup.tar

Common Issues and Fixes

Problem Fix
wsl --install fails Run PowerShell as Administrator; check Windows Update
Very slow file operations on /mnt/c/ Keep projects in ~/ (Linux FS), not /mnt/c/
WSL2 using too much RAM Add memory=4GB to .wslconfig
Port not accessible from Windows Use localhost — WSL2 forwards ports automatically
Cannot connect to internet in WSL2 Run wsl --shutdown and restart; check firewall
GUI apps not displaying Install WSLg (Windows 11) or an X server (Windows 10)

Key Takeaways

  • wsl --install installs everything needed in one command on Windows 10/11
  • Windows drives are accessible at /mnt/c/, /mnt/d/, etc.
  • Keep your code in ~/projects/ (Linux filesystem) for much better performance
  • VS Code with the WSL extension provides a full Linux dev environment inside Windows
  • Use .wslconfig in your Windows home to control WSL2 memory and CPU limits
  • wsl --shutdown and wsl --export are essential for managing your WSL2 instance
← Back to Ubuntu on VirtualBox Next → macOS Terminal Setup

Updated:

You may also enjoy