WSL2 Installation Guide for Windows
Prerequisites
- Windows 10 version 2004 or higher (Build 19041 or higher) or Windows 11
- Administrator access to your Windows machine
- At least 4GB of RAM (8GB recommended)
- Virtualization enabled in BIOS/UEFI
Method 1: Quick Installation (Recommended for Windows 11 and Recent Windows 10)
Step 1: Open PowerShell as Administrator
Right-click on the Start menu and select Windows PowerShell (Admin) or Terminal (Admin).
Step 2: Install WSL with Default Ubuntu
Run the following command:
wsl --install
This single command will:
- Enable the required optional components
- Download the latest Linux kernel
- Set WSL 2 as default
- Install Ubuntu as the default Linux distribution
Step 3: Restart Your Computer
After installation completes, restart your computer.
Step 4: Set Up Your Linux Username and Password
After reboot, Ubuntu will automatically launch and ask you to create a username and password.
# Enter your new UNIX username
# Enter your new password
# Retype your password
Important: This password is for your Linux user and is separate from your Windows password.
Method 2: Manual Installation (For Older Windows 10 Versions)
Step 1: Enable WSL Feature
Open PowerShell as Administrator and run:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Step 2: Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Step 3: Restart Your Computer
Restart Windows to complete the WSL installation.
Step 4: Download and Install the Linux Kernel Update Package
-
Download the WSL2 Linux kernel update package from Microsoft:
-
Run the downloaded
.msifile and follow the installation prompts.
source: https://learn.microsoft.com/en-us/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package
Step 5: Set WSL 2 as Default Version
wsl --set-default-version 2
Step 6: Install a Linux Distribution
Open Microsoft Store and search for your preferred Linux distribution:
- Ubuntu (recommended for beginners)
- Debian
- Kali Linux
- OpenSUSE
- Fedora
Click Get or Install to download and install.
Step 7: Launch and Initialize
- Launch your installed Linux distribution from the Start menu
- Wait for installation to complete
- Create your UNIX username and password
Verifying Your Installation
Check WSL Version
wsl --list --verbose
Expected output:
NAME STATE VERSION
* Ubuntu Running 2
The VERSION column should show 2 for WSL2.
Check Linux Kernel Version
Inside your Linux distribution:
uname -r
You should see something like: 5.15.90.1-microsoft-standard-WSL2
Common WSL Commands
List Installed Distributions
wsl --list --verbose
# or short form
wsl -l -v
Set Default Distribution
wsl --set-default <DistributionName>
# Example:
wsl --set-default Ubuntu
Launch Specific Distribution
wsl -d <DistributionName>
# Example:
wsl -d Ubuntu
Shut Down WSL
wsl --shutdown
Shut Down Specific Distribution
wsl --terminate <DistributionName>
Convert WSL1 to WSL2
wsl --set-version <DistributionName> 2
# Example:
wsl --set-version Ubuntu 2
Unregister/Uninstall a Distribution
wsl --unregister <DistributionName>
Warning: This will delete all data in that distribution!
Post-Installation Setup
Update Your Linux Distribution
After first login, update your packages:
sudo apt update && sudo apt upgrade -y
For other distributions:
- Fedora:
sudo dnf update -y - OpenSUSE:
sudo zypper update -y - Arch:
sudo pacman -Syu
Install Essential Tools
# Build tools
sudo apt install build-essential -y
# Git
sudo apt install git -y
# Curl and wget
sudo apt install curl wget -y
# Python and pip
sudo apt install python3 python3-pip -y
# Node.js (via nvm is recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts
Accessing Windows Files from WSL
Windows drives are automatically mounted under /mnt/:
# Access C: drive
cd /mnt/c
# Access D: drive
cd /mnt/d
# Navigate to your Windows user folder
cd /mnt/c/Users/YourUsername
Accessing WSL Files from Windows
In Windows File Explorer, type in the address bar:
\\wsl$
Or access directly:
\\wsl$\Ubuntu\home\your-linux-username
Troubleshooting
Error: "WSL 2 requires an update to its kernel component"
Download and install the kernel update package from Step 4 in Method 2.
Error: "Please enable the Virtual Machine Platform Windows feature"
Run this in PowerShell as Administrator:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Then restart your computer.
Virtualization Not Enabled
- Restart your computer and enter BIOS/UEFI settings (usually F2, F10, or Delete key during boot)
- Look for Virtualization Technology, Intel VT-x, or AMD-V
- Enable it
- Save and exit
WSL Taking Too Much RAM
Create or edit .wslconfig file in your Windows user folder:
# Navigate to your user folder
cd ~
# Create .wslconfig file
notepad .wslconfig
Add the following content:
[wsl2]
memory=4GB
processors=2
swap=2GB
Save the file and restart WSL:
wsl --shutdown
Distribution Not Starting
Reset the distribution:
wsl --unregister <DistributionName>
Then reinstall from Microsoft Store.
Performance Tips
Use WSL2 File System for Better Performance
Store your project files in the Linux file system (/home/username/) rather than Windows file system (/mnt/c/) for significantly better I/O performance.
# Good - Fast
cd ~
mkdir projects
cd projects
# Avoid - Slower
cd /mnt/c/Users/YourName/projects
Enable systemd (Optional)
Edit /etc/wsl.conf:
sudo nano /etc/wsl.conf
Add:
[boot]
systemd=true
Save and restart WSL:
wsl --shutdown
Useful Resources
Next Steps
After installing WSL2, you can:
- Install Docker Desktop - It integrates seamlessly with WSL2
- Set up your development environment - Install languages, frameworks, and tools
- Use VS Code with WSL - Install the "Remote - WSL" extension
- Configure your shell - Try Zsh with Oh My Zsh for better experience
# Install Zsh and Oh My Zsh
sudo apt install zsh -y
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
Enjoy your Linux environment on Windows! 🐧
