Complete WSL (Windows Subsystem for Linux) Setup Guide

A comprehensive, step-by-step guide to install and configure WSL2 on Windows 10/11, set up Ubuntu, and create user accounts with full administrative access.

---

📋 Table of Contents

1. Prerequisites & System Requirements
2. Quick Automatic Installation (Recommended)
3. Manual Installation Method
4. Installing Ubuntu Distribution
5. Verify WSL Installation
6. Creating a User Account in Ubuntu
7. Setting Default User for WSL Distribution
8. Post-Installation Setup
9. Essential WSL Commands
10. Troubleshooting

---

Prerequisites & System Requirements

Supported Windows Versions

• Windows 11: Full native support for wsl --install
• Windows 10: Build 2004 or higher (Build 19041+)

Check Your Windows Version

Open PowerShell and run:

winver

Verify Virtualization is Enabled

Open PowerShell as Administrator and run:

systeminfo

Look for the line:

Hyper-V Requirements: Virtualization Enabled In Firmware: Yes

If virtualization is disabled:

1. Restart your computer
2. Enter BIOS/UEFI settings (usually F2, F10, Del, or Esc during boot)
3. Enable "Intel VT-x" or "AMD-V" (exact name varies by manufacturer)
4. Save and exit

---

Quick Automatic Installation (Recommended)

This is the easiest method for Windows 11 and recent Windows 10 builds.

Step 1: Open PowerShell as Administrator

• Press Win + X
• Select "Windows PowerShell (Admin)" or "Terminal (Admin)"

Step 2: Install WSL with Default Ubuntu

wsl --install

This single command will:

• Enable WSL feature
• Install WSL2 Linux kernel
• Set WSL2 as default
• Install Ubuntu (latest LTS version)

Step 3: Reboot Your Computer

Restart-Computer

Or manually restart your computer when prompted.

Step 4: Install Specific Ubuntu Version (Optional)

To install a specific Ubuntu distribution:

wsl --install -d Ubuntu-22.04

Step 5: Update WSL Kernel

wsl --update

---

Manual Installation Method

Use this method if wsl --install is not available on your system.

Step 1: Open PowerShell as Administrator

Step 2: Enable WSL Feature

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

Step 3: Enable Virtual Machine Platform

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

Step 4: Restart Your Computer

Restart-Computer

Step 5: Download WSL2 Linux Kernel Update

1. Download the WSL2 Linux kernel update package
2. Run the installer (wsl_update_x64.msi)

Step 6: Set WSL2 as Default Version

Open PowerShell as Administrator:

wsl --set-default-version 2

---

Installing Ubuntu Distribution

Method 1: Microsoft Store (Recommended)

1. Open Microsoft Store
2. Search for "Ubuntu"
3. Choose your preferred version:
   • Ubuntu (latest LTS)
   • Ubuntu 22.04 LTS
   • Ubuntu 20.04 LTS
4. Click "Install"
5. Wait for installation to complete
6. Click "Launch" or find it in Start Menu

Method 2: Command Line

wsl --install -d Ubuntu-22.04

List All Available Distributions

wsl --list --online

Or shorthand:

wsl -l -o

---

Verify WSL Installation

Check Installed Distributions

wsl --list --verbose

Or shorthand:

wsl -l -v

Expected output:

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

Verify WSL2 is Active

The VERSION column should show 2. If it shows 1, convert it:

wsl --set-version Ubuntu-22.04 2

Set Default Distribution

wsl --set-default Ubuntu-22.04

---

Creating a User Account in Ubuntu

Scenario 1: First Launch (Automatic Setup)

When you first launch Ubuntu from the Start Menu, it will automatically prompt you to:

1. Create a username
2. Set a password
3. Confirm password

Important Notes:

• Username should be lowercase, no spaces
• Password won't show while typing (normal behavior)
• Remember this password - you'll need it for sudo commands

Scenario 2: Manual User Creation (Advanced)

If you need to create additional users or the automatic setup didn't occur:

Step 1: Access Ubuntu as Root

From PowerShell:

wsl -d Ubuntu-22.04 -u root

Step 2: Create New User with adduser (Recommended)

adduser shreyas

You'll be prompted to enter:

• Password (twice)
• Full Name (optional, press Enter to skip)
• Room Number (optional, press Enter to skip)
• Work Phone (optional, press Enter to skip)
• Home Phone (optional, press Enter to skip)
• Other (optional, press Enter to skip)

The adduser command automatically:

• Creates home directory (/home/shreyas)
• Sets up default shell
• Copies skeleton files from /etc/skel
• Creates user group

Step 3: Grant Sudo Privileges

usermod -aG sudo shreyas

This adds the user to the sudo group, allowing administrative commands.

Step 4: Verify Sudo Access

Switch to the new user:

su - shreyas

Test sudo privileges:

sudo -v

Enter your password when prompted. If successful, you'll see no errors.

Step 5: Exit Root Shell

exit

Alternative: Using useradd (Advanced Users Only)

The useradd command requires more manual configuration:

# Create user with home directory and bash shell
useradd -m -s /bin/bash shreyas

# Set password
passwd shreyas

# Add to sudo group
usermod -aG sudo shreyas

Note: adduser is recommended for beginners as it's interactive and handles defaults automatically.

---

Setting Default User for WSL Distribution

After creating a user, you'll want to set them as the default login user.

Method 1: Using /etc/wsl.conf (Universal Method)

Step 1: Launch Ubuntu as Root

From PowerShell:

wsl -d Ubuntu-22.04 -u root

Step 2: Create or Edit /etc/wsl.conf

nano /etc/wsl.conf

Step 3: Add Default User Configuration

Add these lines:

[user]
default=shreyas

Replace shreyas with your actual username.

Step 4: Save and Exit

• Press Ctrl + O to save
• Press Enter to confirm
• Press Ctrl + X to exit

Step 5: Terminate WSL Distribution

Exit the Ubuntu shell, then from PowerShell:

wsl --terminate Ubuntu-22.04

Step 6: Restart Ubuntu

Launch Ubuntu again from Start Menu or:

wsl -d Ubuntu-22.04

You should now login as your specified user automatically.

Method 2: Ubuntu-Specific Command (Quick Method)

From PowerShell (not inside WSL):

ubuntu2204 config --default-user shreyas

Notes:

• Command name varies by distro: ubuntu, ubuntu2204, ubuntu2004, etc.
• Check exact command by looking at the app name in Start Menu
• This method may not work for all distributions

To verify which command to use:

wsl -l

---

Post-Installation Setup

Update Package Lists and Upgrade

sudo apt update && sudo apt upgrade -y

Install Essential Build Tools

sudo apt install -y build-essential git curl wget ca-certificates

Install Additional Development Tools

Python and Pip

sudo apt install -y python3 python3-pip

Node.js via NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

Close and reopen your terminal, then:

nvm install --lts

Docker (Optional)

Follow official Docker documentation for WSL2-specific instructions.

Configure Git

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Visual Studio Code Integration

1. Install VS Code on Windows
2. Install "Remote - WSL" extension in VS Code
3. From WSL terminal, navigate to your project:

   cd ~/projects
   code .

Windows Terminal (Highly Recommended)

1. Install from Microsoft Store: "Windows Terminal"
2. Ubuntu will automatically appear as a profile
3. Set Ubuntu as default (optional):
   • Open Settings (Ctrl + ,)
   • Set "Default profile" to Ubuntu

---

Essential WSL Commands

List All Distributions

wsl --list --verbose

Or: wsl -l -v

Launch Specific Distribution

wsl -d Ubuntu-22.04

Launch as Specific User

wsl -d Ubuntu-22.04 -u shreyas

Launch as Root

wsl -d Ubuntu-22.04 -u root

Run Single Command

wsl -d Ubuntu-22.04 -- ls -la /home

Set Default Distribution

wsl --set-default Ubuntu-22.04

Terminate Running Distribution

wsl --terminate Ubuntu-22.04

Shutdown All WSL Instances

wsl --shutdown

Update WSL

wsl --update

Check WSL Version

wsl --version

Export Distribution (Backup)

wsl --export Ubuntu-22.04 C:\backup\ubuntu-backup.tar

Import Distribution (Restore)

wsl --import Ubuntu-Restored C:\WSL\Ubuntu-Restored C:\backup\ubuntu-backup.tar --version 2

Unregister Distribution (Delete)

wsl --unregister Ubuntu-22.04

⚠️ Warning: This permanently deletes all data in the distribution!

---

Troubleshooting

Issue: "WSL 2 requires an update to its kernel component"

Solution:

1. Download the kernel update: https://aka.ms/wsl2kernel
2. Install the MSI package
3. Run: wsl --update

Issue: Virtualization Not Enabled

Solution:

1. Restart computer and enter BIOS/UEFI
2. Find "Virtualization Technology", "Intel VT-x", or "AMD-V"
3. Enable it
4. Save and exit BIOS

Issue: "wsl --install" Command Not Found

Solution: You're on an older Windows build. Use the Manual Installation Method.

Issue: Distribution Stuck in "Installing" State

Solution:

wsl --shutdown
wsl --unregister Ubuntu-22.04
wsl --install -d Ubuntu-22.04

Issue: Can't Access Windows Files from Ubuntu

Solution: Windows drives are mounted under /mnt/:

cd /mnt/c/Users/YourUsername/Documents

Issue: Can't Access Ubuntu Files from Windows

Solution: Ubuntu filesystem is accessible from Windows at:

\\wsl$\Ubuntu-22.04\home\shreyas

Or type \\wsl$ in File Explorer address bar.

Issue: Default User is Root After Import

Solution: Create /etc/wsl.conf as described in Setting Default User.

Issue: Password Not Working for Sudo

Solution: Reset password as root:

wsl -d Ubuntu-22.04 -u root

Then inside Ubuntu:

passwd shreyas

Issue: Network/Internet Not Working in WSL

Solution:

wsl --shutdown

Then restart your distribution. If problem persists:

netsh winsock reset
netsh int ip reset all

Restart Windows.

---

Additional Resources

• Official Microsoft WSL Documentation
• WSL GitHub Repository
• Ubuntu WSL Documentation

---

Contributing

Found an error or have suggestions? Please open an issue or submit a pull request!

---

License

This guide is provided as-is for educational purposes.

---

Last Updated: December 2025