How To Install WSL2 on Windows 10/11: Complete Step-by-Step Guide

1. Introduction to WSL and WSL2

Windows Subsystem for Linux (WSL) revolutionizes how developers work on Windows by providing a complete Linux environment without the overhead of traditional virtual machines. Whether you’re a developer working with Linux tools, a system administrator managing cross-platform environments, or a student learning Linux commands, WSL2 offers the perfect solution.

Understanding the difference between WSL1 and WSL2 is crucial for making the right choice for your workflow:

WSL2 provides a more complete Linux experience with better compatibility, performance improvements for file-intensive operations, and full Docker support. It’s the recommended choice for most users, especially developers working with containers or requiring full Linux kernel features.

2. System Requirements

Before beginning the installation process, ensure your Windows system meets the minimum requirements. WSL2 has specific version requirements that must be satisfied for proper operation.

The version requirement exists because WSL2 relies on Hyper-V technology and the Windows Hypervisor Platform, which were significantly improved in these Windows versions. Earlier versions lack the necessary kernel features for WSL2’s virtual machine architecture.

3. Check Windows Version

Verifying your Windows version is the first critical step. This ensures compatibility and determines which installation method you’ll use.

# Alternative: Check version via Command Prompt
winver

# Or use PowerShell to get detailed information
Get-ComputerInfo | Select WindowsProductName, WindowsVersion, WindowsBuildLabEx

If your Windows version is older than the requirements, you’ll need to update through Windows Update before proceeding. Older versions cannot run WSL2 due to missing kernel features and Hyper-V improvements.

4. Enable WSL and Virtual Machine Platform Features

WSL2 requires two Windows optional features to be enabled: the Windows Subsystem for Linux and the Virtual Machine Platform. These features provide the foundation for running Linux distributions and the hypervisor capabilities needed for WSL2’s architecture.

4.1 Quick Installation (Windows 10 Build 20H1 and Later)

For newer Windows versions, Microsoft provides a simplified installation command that handles most of the setup automatically:

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

# This command automatically:
# - Enables WSL and Virtual Machine Platform features
# - Downloads and installs the WSL2 Linux kernel
# - Sets WSL2 as default
# - Installs Ubuntu (default distribution)

4.2 Manual Installation (All Windows Versions)

For older Windows versions or when you need more control over the installation process, use the manual method:

# Enable Windows Subsystem for Linux
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Alternative: Using PowerShell cmdlets
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -NoRestart
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart

After running these commands, restart your computer to apply the changes. The restart is essential as these features modify core Windows functionality and require a system reboot to take effect.

# Check if WSL features are enabled
dism.exe /online /get-featureinfo /featurename:Microsoft-Windows-Subsystem-Linux
dism.exe /online /get-featureinfo /featurename:VirtualMachinePlatform

# Look for "State : Enabled" in the output

5. Install WSL2 Kernel Update

The WSL2 Linux kernel update package is crucial for WSL2 functionality. This package contains the Linux kernel that WSL2 uses to run Linux distributions. While newer Windows versions may include this automatically, manual installation ensures you have the latest version.

5.1 Download and Install Kernel Update

5.2 Verify Kernel Installation

After installing the kernel update, you can verify the installation and check the kernel version:

# Check WSL kernel version
wsl --version

# If WSL is already running a distribution, check kernel from within Linux
uname -r

# Expected output format: 5.15.x.x-microsoft-standard-WSL2

6. Set WSL2 as Default Version

Setting WSL2 as the default version ensures that any new Linux distributions you install will automatically use WSL2 architecture. This step is important because some installation methods default to WSL1 for compatibility reasons.

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

# Verify the default version setting
wsl --status

# Expected output should show "Default Version: 2"

7. Install a Linux Distribution

With WSL2 properly configured, you can now install your preferred Linux distribution. Microsoft Store offers several popular distributions, each with its own strengths and target audiences.

7.1 Available Distributions

7.2 Installation Methods

# Method 2: Command Line Installation
# List available distributions
wsl --list --online

# Install specific distribution (example: Ubuntu)
wsl --install -d Ubuntu

# Install specific version
wsl --install -d Ubuntu-20.04

7.3 First Launch and Setup

When you first launch your Linux distribution, several important setup steps occur automatically:

# After initial setup, update package repositories
sudo apt update && sudo apt upgrade -y

# Install essential development tools (Ubuntu/Debian)
sudo apt install -y curl wget git vim build-essential

# Verify installation
lsb_release -a
whoami
pwd

8. Updating from WSL1 to WSL2

If you already have WSL1 distributions installed, you can upgrade them to WSL2 to benefit from improved performance and compatibility. This process converts your existing Linux installation while preserving all your files and configurations.

8.1 Check Current WSL Version

# List all installed distributions with their WSL versions
wsl --list --verbose
wsl -l -v

# Example output:
# NAME      STATE           VERSION
# Ubuntu    Running         1
# Debian    Stopped         2

8.2 Convert Distribution to WSL2

# Convert specific distribution to WSL2
wsl --set-version Ubuntu 2

# Monitor conversion progress (it will show percentage)
# When complete, verify the conversion
wsl -l -v

# The VERSION column should now show "2"

# Export distribution before conversion
wsl --export Ubuntu C:\Backup\Ubuntu-backup.tar

# After successful conversion and testing, you can remove the backup

9. Advanced Configuration

WSL2 offers extensive configuration options to optimize performance and resource usage for your specific needs. The primary configuration file is .wslconfig, which controls global WSL2 settings.

9.1 Creating .wslconfig File

The .wslconfig file should be placed in your Windows user directory (C:\Users\[YourUsername]\.wslconfig) and contains global settings that apply to all WSL2 distributions.

# Create .wslconfig file in your Windows user directory
# File location: C:\Users\[YourUsername]\.wslconfig

[wsl2]
# Limits VM memory to use no more than 4 GB (adjust based on your system)
memory=4GB

# Sets the VM to use 4 virtual processors (adjust based on your CPU)
processors=4

# Sets amount of swap storage space to 2GB, default is 25% of available RAM
swap=2GB

# Sets swapfile path location, default is %USERPROFILE%\AppData\Local\Temp\swap.vhdx
swapfile=C:\\temp\\wsl-swap.vhdx

# Disable page reporting so WSL retains all allocated memory claimed from Windows
pageReporting=false

# Turn on default connection to bind WSL 2 localhost to Windows localhost
localhostforwarding=true

# Disables nested virtualization
nestedVirtualization=false

# Turns on output console showing contents of dmesg when opening a WSL 2 distro for debugging
debugConsole=true

9.2 Per-Distribution Configuration

You can also configure individual distributions using wsl.conf files placed within each Linux distribution at /etc/wsl.conf:

# Create /etc/wsl.conf inside your Linux distribution
sudo nano /etc/wsl.conf

# Example configuration:
[boot]
systemd=true
command="service docker start"

[user]
default=yourusername

[network]
generateHosts=true
generateResolvConf=true

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

[filesystem]
umask=022

9.3 Restart WSL After Configuration Changes

# Restart all WSL distributions to apply configuration changes
wsl --shutdown

# Wait a few seconds, then restart your distribution
wsl -d Ubuntu

# Verify configuration is applied
# Check memory limit from within Linux
free -h

# Check processor count
nproc

10. File System Access

One of WSL2’s most powerful features is seamless file system integration between Windows and Linux. Understanding how to efficiently access files in both directions is crucial for productive development workflows.

10.1 Accessing WSL Files from Windows

WSL2 makes your Linux file systems accessible through Windows Explorer using a special network path. This integration allows you to use Windows applications to edit Linux files directly.

# Method 2: Direct path access
# From Windows Explorer address bar:
\\wsl$\Ubuntu\home\yourusername

# Method 3: Open Windows Explorer from Linux
# Run this command inside your WSL distribution:
explorer.exe .

# This opens Windows Explorer at your current Linux directory

10.2 Accessing Windows Files from WSL

All Windows drives are automatically mounted under /mnt directory in WSL, making Windows files easily accessible from Linux command line tools and applications.

# Navigate to Windows C: drive
cd /mnt/c

# Access your Windows user directory
cd /mnt/c/Users/$USER

# Access Windows Documents folder
cd /mnt/c/Users/$USER/Documents

# List all mounted Windows drives
ls /mnt/

# Create alias for quick access (add to ~/.bashrc)
echo "alias cdwin='cd /mnt/c/Users/$USER'" >> ~/.bashrc

WSL terminal accessing Windows files through /mnt directory structure

10.3 Performance Considerations

# Create development directory in Linux filesystem
mkdir ~/development
cd ~/development

# Clone repositories here for best performance
git clone https://github.com/example/repo.git

# Access from Windows via:
# \\wsl$\Ubuntu\home\yourusername\development

11. Troubleshooting

Even with proper installation, you might encounter various issues with WSL2. This section covers the most common problems and their solutions, helping you quickly resolve issues and get back to productive work.

11.1 Common Installation Issues

Virtual Machine Platform Not Enabled

# Error: "Please enable the Virtual Machine Platform Windows feature"
# Solution: Enable the feature and restart

# Via PowerShell (Run as Administrator):
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart

# Via DISM:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Then restart your computer

Kernel Update Issues

# Error: "The kernel file does not exist"
# Solution: Download and install the latest kernel update

# Download from: https://aka.ms/wsl2kernel
# Or use winget (if available):
winget install Microsoft.WSL

# Verify installation:
wsl --version

11.2 Runtime Issues

WSL2 Distribution Won’t Start

# Check WSL status and distribution state
wsl --status
wsl -l -v

# Restart WSL completely
wsl --shutdown
wsl -d YourDistributionName

# If still failing, try restarting LxssManager service
# Run in elevated PowerShell:
Restart-Service LxssManager

Network Connectivity Issues

# Test network connectivity from within WSL
ping google.com
nslookup google.com

# If DNS resolution fails, try regenerating resolv.conf
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

# Or restart WSL networking
wsl --shutdown
# Wait 10 seconds, then restart distribution

11.3 Performance Issues

# Check memory usage
free -h

# Check disk usage  
df -h

# Monitor system resources
htop

# If running out of memory, adjust .wslconfig:
# Increase memory allocation or reduce running processes

11.4 File Permission Issues

# Fix common file permission issues
# If Windows files show wrong permissions in WSL:

# Method 1: Mount with proper options
sudo umount /mnt/c
sudo mount -t drvfs C: /mnt/c -o metadata,uid=1000,gid=1000,umask=022

# Method 2: Configure in /etc/wsl.conf
sudo nano /etc/wsl.conf
# Add:
[automount]
options = "metadata,umask=022,fmask=11"

# WSL diagnostic information
wsl --version
wsl --status
wsl -l -v

# Windows version
winver

# Check Hyper-V status
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All

12. Useful WSL Commands

Mastering essential WSL commands significantly improves your productivity when managing Linux distributions and switching between Windows and Linux environments.

12.1 Distribution Management

# List all installed distributions
wsl --list --verbose
wsl -l -v

# List available distributions for installation
wsl --list --online
wsl -l -o

# Install specific distribution
wsl --install -d Ubuntu-20.04

# Set default distribution
wsl --set-default Ubuntu

# Launch specific distribution
wsl -d Ubuntu
wsl --distribution Ubuntu

12.2 Version and State Management

# Convert distribution to WSL2
wsl --set-version Ubuntu 2

# Set default WSL version for new installations
wsl --set-default-version 2

# Terminate specific distribution
wsl --terminate Ubuntu

# Shutdown all WSL distributions
wsl --shutdown

# Check WSL status and version
wsl --status
wsl --version

12.3 Import/Export and Backup

# Export distribution to backup file
wsl --export Ubuntu C:\Backups\Ubuntu-backup.tar

# Import distribution from backup
wsl --import Ubuntu-Restored C:\WSL\Ubuntu-Restored C:\Backups\Ubuntu-backup.tar

# Unregister (delete) distribution
wsl --unregister Ubuntu

# Note: --unregister permanently deletes the distribution and all data

12.4 Advanced Commands

# Execute command in specific distribution without launching shell
wsl -d Ubuntu -- ls -la

# Run command as specific user
wsl -d Ubuntu -u root -- apt update

# Mount Windows drive with specific options
wsl --mount \\.\PHYSICALDRIVE1 --partition 1

# Unmount drive
wsl --unmount \\.\PHYSICALDRIVE1

12.5 Quick Navigation Commands

# Launch Windows Explorer from Linux current directory
explorer.exe .

# Open Windows file/folder from Linux
explorer.exe /mnt/c/Users/$USER/Documents

# Launch Windows applications from Linux
notepad.exe filename.txt
code .  # Visual Studio Code

# Access Linux files from Windows Command Prompt
wsl ls -la

13. Frequently Asked Questions

❓ How do I know if WSL2 is working correctly?

Answer: Run wsl --status to check WSL version and state. Inside your Linux distribution, run uname -r – you should see output containing “microsoft-standard-WSL2”.

# Verify WSL2 is running
wsl --status
wsl -l -v

# Check kernel version from within Linux
uname -r
# Expected output: 5.15.x.x-microsoft-standard-WSL2

❓ Why is WSL2 using so much memory?

Answer: WSL2 dynamically allocates memory up to 50% of system RAM by default. This is normal behavior – memory is released when not needed. You can limit memory usage by creating a .wslconfig file in your Windows user directory.

# Check current memory usage
free -h

# Create .wslconfig to limit memory (in Windows user directory)
[wsl2]
memory=4GB  # Adjust based on your needs

❓ Can I run Docker in WSL2?

Answer: Yes! WSL2 has full Docker support. You can install Docker directly in your Linux distribution or use Docker Desktop for Windows with WSL2 backend for better integration.

# Install Docker in WSL2 (Ubuntu example)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Start Docker service (if systemd not enabled)
sudo service docker start

❓ How do I transfer files between Windows and WSL2?

Answer: Use the \\wsl$ network path to access WSL files from Windows, or navigate to /mnt/c to access Windows files from WSL2. For best performance, keep project files in the Linux filesystem.

# Access WSL files from Windows Explorer:
\\wsl$\Ubuntu\home\username

# Access Windows files from WSL2:
cd /mnt/c/Users/YourWindowsUsername

# Copy files between systems:
cp /mnt/c/source/file.txt ~/destination/

❓ Why is file access slow between Windows and WSL2?

Answer: Cross-filesystem operations are slower due to the virtualization layer. For optimal performance, store frequently accessed files in the same filesystem where you’ll primarily work with them.

❓ Can I run GUI applications in WSL2?

Answer: Yes! WSL2 supports GUI applications through WSLg (Windows Subsystem for Linux GUI). This feature is available in Windows 11 and recent Windows 10 builds with graphical Linux apps running natively.

# Install GUI application (example: Firefox)
sudo apt update
sudo apt install firefox

# Launch GUI application
firefox &

# The application window will appear on your Windows desktop

❓ How do I update my Linux distribution in WSL2?

Answer: Use your distribution’s package manager just like on a regular Linux system. WSL2 provides full Linux functionality including package management.

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

# CentOS/RHEL/Fedora systems:
sudo yum update -y
# or
sudo dnf update -y

# Alpine Linux:
sudo apk update && sudo apk upgrade

Conclusion

WSL2 represents a significant advancement in cross-platform development, offering Windows users a complete, high-performance Linux environment without the complexity of traditional virtual machines. Throughout this guide, we’ve covered everything from basic installation to advanced configuration and troubleshooting.

Key takeaways from this comprehensive guide:

• System compatibility: Ensure your Windows version meets requirements (1903+ for Windows 10, all Windows 11 versions)
• Installation approaches: Use wsl --install for newer systems, or manual feature enabling for older versions
• Performance optimization: Configure memory and processor allocation through .wslconfig for optimal resource usage
• File system strategy: Store development files in Linux filesystem for best performance while maintaining Windows accessibility
• Distribution management: Master essential commands for managing multiple distributions and versions

Start with the basic installation if you’re new to WSL2, then gradually explore advanced features like custom configurations, GUI applications, and Docker integration as your needs evolve. The seamless integration between Windows and Linux environments makes WSL2 an invaluable tool for modern development workflows.

Remember that WSL2 is actively developed by Microsoft with regular updates and improvements. Stay updated with the latest features and enhancements through Windows Update and the official WSL documentation.