DEV Community

karoon sillapapan
karoon sillapapan

Posted on

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

You should see output similar to:

  NAME              STATE           VERSION
* Ubuntu-24.04      Running         2
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

2. Export Your Current Distribution 

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

5. Set as Default and Verify 

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

# Verify the setup
wsl --list --verbose
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

  1. Store project files within the WSL filesystem for better performance, not on Windows drives
  2. Use VS Code's Remote WSL extension for seamless development
  3. Regularly back up your WSL distribution using the export command
  4. 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
Enter fullscreen mode Exit fullscreen mode

Resources

License

This guide is provided under the MIT License.

Top comments (0)