WSL2 Setup Guide for Windows

WSL2 Setup Guide for Windows This guide walks you through setting up Windows Subsystem for Linux 2 (WSL2) on Windows, including installation, customization, and best practices. Prerequisites Windows 10 version 2004 or higher (Build 19041 or higher) or Windows 11 Administrator access to your Windows machine At least 8GB of RAM recommended 20GB+ of free disk space Installation Steps 1. Enable WSL via PowerShell Open PowerShell as Administrator and run: # Install WSL with default Ubuntu distribution # This also enables required Windows features wsl --install After installation completes, restart your computer to finalize the setup. 2. Install a Specific Linux Distribution After restart, open PowerShell as Administrator again: # See available distributions wsl --list --online # Install Ubuntu 24.04 LTS wsl --install -d Ubuntu-24.04 When prompted, create a username and password for your Linux distribution. 3. Verify Installation Check that your distribution is installed correctly: # List installed distributions and their WSL versions wsl --list --verbose You should see output similar to: NAME STATE VERSION * Ubuntu-24.04 Running 2 The asterisk (*) indicates your default distribution. Moving WSL to Another Drive (Optional) This is useful to save space on your system drive (C:). 1. Create Destination Directory # Create a folder on your target drive mkdir D:\WSL 2. Export Your Current Distribution # Create a backup of your distribution wsl --export Ubuntu-24.04 D:\WSL\ubuntu_backup.tar 3. Unregister the Current Distribution # Remove the current registration (this will delete all data inside the distribution) # Make sure you've exported the backup first! wsl --unregister Ubuntu-24.04 4. Import the Backup to New Location # Import from backup to the new location wsl --import Ubuntu-24.04 D:\WSL\Ubuntu D:\WSL\ubuntu_backup.tar --version 2 5. Set as Default and Verify # Set as default distribution wsl --set-default Ubuntu-24.04 # Verify the setup wsl --list --verbose Basic WSL Commands # Start your default WSL distribution wsl # Start a specific distribution wsl -d Ubuntu-24.04 # Terminate (shutdown) a running distribution wsl -t Ubuntu-24.04 # Set WSL version for a distribution wsl --set-version Ubuntu-24.04 2 # Update WSL itself wsl --update Setting Up Your Linux Environment After installation, you'll want to update your Linux distribution: # Update package lists and upgrade installed packages sudo apt update && sudo apt upgrade -y # Install common development tools sudo apt install build-essential git curl wget -y File System Access Access Windows files from WSL at /mnt/c/, /mnt/d/, etc. Access WSL files from Windows at \\wsl$\Ubuntu-24.04\home\username\ Best Practices Store project files within the WSL filesystem for better performance, not on Windows drives Use VS Code's Remote WSL extension for seamless development Regularly back up your WSL distribution using the export command Set resource limits in .wslconfig if WSL consumes too many resources Troubleshooting If you encounter issues: WSL not starting: Run wsl --shutdown and then try again Network issues: Restart the LxssManager service in Windows Disk space errors: Clean up your WSL instance or increase virtual disk size Performance problems: Ensure your files are on the Linux filesystem, not Windows Advanced Configuration Create or edit the .wslconfig file in your Windows user directory (C:\Users\YourUsername\.wslconfig): [wsl2] memory=4GB processors=2 localhostForwarding=true Resources Microsoft WSL Documentation Ubuntu WSL Documentation VS Code Remote WSL Extension License This guide is provided under the MIT License.

May 7, 2025 - 03:50

WSL2 Setup Guide for Windows

This guide walks you through setting up Windows Subsystem for Linux 2 (WSL2) on Windows, including installation, customization, and best practices.

Prerequisites

Windows 10 version 2004 or higher (Build 19041 or higher) or Windows 11
Administrator access to your Windows machine
At least 8GB of RAM recommended
20GB+ of free disk space

Installation Steps

1. Enable WSL via PowerShell

Open PowerShell as Administrator and run:

# Install WSL with default Ubuntu distribution
# This also enables required Windows features
wsl --install

After installation completes, restart your computer to finalize the setup.

2. Install a Specific Linux Distribution

After restart, open PowerShell as Administrator again:

# See available distributions
wsl --list --online

# Install Ubuntu 24.04 LTS
wsl --install -d Ubuntu-24.04

When prompted, create a username and password for your Linux distribution.

3. Verify Installation

Check that your distribution is installed correctly:

# List installed distributions and their WSL versions
wsl --list --verbose

You should see output similar to:

  NAME              STATE           VERSION
* Ubuntu-24.04      Running         2

The asterisk (*) indicates your default distribution.

Moving WSL to Another Drive (Optional)

This is useful to save space on your system drive (C:).

1. Create Destination Directory

# Create a folder on your target drive
mkdir D:\WSL

2. Export Your Current Distribution

# Create a backup of your distribution
wsl --export Ubuntu-24.04 D:\WSL\ubuntu_backup.tar

3. Unregister the Current Distribution

# Remove the current registration (this will delete all data inside the distribution)
# Make sure you've exported the backup first!
wsl --unregister Ubuntu-24.04

4. Import the Backup to New Location

# Import from backup to the new location
wsl --import Ubuntu-24.04 D:\WSL\Ubuntu D:\WSL\ubuntu_backup.tar --version 2

5. Set as Default and Verify

# Set as default distribution
wsl --set-default Ubuntu-24.04

# Verify the setup
wsl --list --verbose

Basic WSL Commands

# Start your default WSL distribution
wsl

# Start a specific distribution
wsl -d Ubuntu-24.04

# Terminate (shutdown) a running distribution
wsl -t Ubuntu-24.04

# Set WSL version for a distribution
wsl --set-version Ubuntu-24.04 2

# Update WSL itself
wsl --update

Setting Up Your Linux Environment

After installation, you'll want to update your Linux distribution:

# Update package lists and upgrade installed packages
sudo apt update && sudo apt upgrade -y

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

File System Access

Access Windows files from WSL at /mnt/c/, /mnt/d/, etc.
Access WSL files from Windows at \\wsl$\Ubuntu-24.04\home\username\

Best Practices

Store project files within the WSL filesystem for better performance, not on Windows drives
Use VS Code's Remote WSL extension for seamless development
Regularly back up your WSL distribution using the export command
Set resource limits in .wslconfig if WSL consumes too many resources

Troubleshooting

If you encounter issues:

WSL not starting: Run wsl --shutdown and then try again
Network issues: Restart the LxssManager service in Windows
Disk space errors: Clean up your WSL instance or increase virtual disk size
Performance problems: Ensure your files are on the Linux filesystem, not Windows

Advanced Configuration

Create or edit the .wslconfig file in your Windows user directory (C:\Users\YourUsername\.wslconfig):

[wsl2]
memory=4GB
processors=2
localhostForwarding=true

Resources

License

This guide is provided under the MIT License.