What Is WSL2?Installing WSL2Distro ManagementInitial SetupVS Code IntegrationFilesystem InteropWSL Network SettingsWSL Management CommandsSummary
windowswsllinuxdev-environment

Complete WSL2 Setup Guide — Installation, Distros, and VS Code Integration

· 5 min read

What Is WSL2?

WSL2 (Windows Subsystem for Linux 2) is a lightweight virtualization technology that runs a native Linux kernel on Windows. While WSL1 translated system calls, WSL2 runs an actual Linux kernel on top of Hyper-V. This brought major improvements in Docker support, systemd, and filesystem performance.

This article walks through WSL2 installation, Ubuntu distro setup, VS Code integration, and filesystem interop step by step.

Installing WSL2

If you have Windows 10 (build 19041 or later) or Windows 11, you can install with a single command.

# Install WSL (default distro: Ubuntu)
wsl --install

# Reboot required after installation
# After reboot, the Ubuntu username/password setup screen appears

# Check WSL version
wsl --version
# Sample output:
# WSL version: 2.0.9.0
# Kernel version: 5.15.133.1-1
# WSLg version: 1.0.59

If WSL1 is already installed, you can upgrade to WSL2.

# Set default WSL version to 2
wsl --set-default-version 2

# Convert existing distro to WSL2
wsl --set-version Ubuntu 2

# Check conversion status
wsl --list --verbose
# Sample output:
#   NAME      STATE    VERSION
# * Ubuntu    Running  2

Distro Management

WSL allows installing multiple Linux distributions simultaneously. Splitting by use case is convenient.

# List available distros
wsl --list --online
# Sample output:
# NAME                   FRIENDLY NAME
# Ubuntu                 Ubuntu
# Ubuntu-22.04           Ubuntu 22.04 LTS
# Ubuntu-24.04           Ubuntu 24.04 LTS
# Debian                 Debian GNU/Linux
# openSUSE-Leap-15.6     openSUSE Leap 15.6

# Install a specific distro
wsl --install -d Ubuntu-24.04

# Change default distro
wsl --set-default Ubuntu-24.04

# Export distro (backup)
wsl --export Ubuntu-24.04 D:\backup\ubuntu-24.04.tar

# Import distro (restore)
wsl --import Ubuntu-Restore D:\wsl\ubuntu-restore D:\backup\ubuntu-24.04.tar

Initial Setup

After installing a distro, update base packages and install development tools.

# Update packages
sudo apt update && sudo apt upgrade -y

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

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "email@example.com"

# Install Node.js (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version
# Sample output: v22.11.0

VS Code Integration

Using VS Code’s Remote - WSL extension lets you edit files inside WSL directly from Windows VS Code. The terminal, debugger, and extensions all run within the WSL environment.

# Open VS Code from WSL terminal
code .
# On first run, VS Code Server is automatically installed inside WSL

# Open a specific file
code ~/project/main.py

# Open a specific folder in VS Code
code ~/my-project

You can also set WSL as the default terminal in VS Code settings.

// settings.json
{
  "terminal.integrated.defaultProfile.windows": "Ubuntu (WSL)",
  "remote.WSL.fileWatcher.polling": true
}

Filesystem Interop

In WSL2, the Linux filesystem and Windows filesystem can access each other. However, you need to understand the performance differences.

# Access Windows files from WSL
ls /mnt/c/Users/
# Windows C: drive is mounted at /mnt/c

# Navigate to Windows Desktop
cd /mnt/c/Users/username/Desktop

# Run Windows programs from WSL
explorer.exe .        # Open current directory in Windows Explorer
notepad.exe file.txt  # Open file with Notepad

To access WSL files from Windows, use the \\wsl$ network path.

# Access WSL files in Windows Explorer
# Enter in the address bar:
# \\wsl$\Ubuntu\home\username

# Access WSL files from PowerShell
dir \\wsl$\Ubuntu\home\

Performance tip: Keep project files on the WSL filesystem (~/) for best performance. The /mnt/c/ path involves cross-filesystem access, which has slower I/O.

WSL Network Settings

WSL2 uses a separate virtual network adapter. Port forwarding or host access configuration may be needed.

# Check WSL internal IP
ip addr show eth0 | grep inet
# Sample output: inet 172.28.123.45/20

# Accessing WSL services from Windows
# Auto-forwarded via localhost (e.g., when running a server on port 3000 in WSL)
# Access http://localhost:3000 from a Windows browser

You can control WSL2 resources with the .wslconfig file.

# %UserProfile%\.wslconfig
[wsl2]
memory=8GB          # Maximum memory allocated to WSL2
processors=4        # Number of CPU cores to use
swap=4GB            # Swap size
localhostForwarding=true  # Enable localhost forwarding

[experimental]
autoMemoryReclaim=gradual  # Automatic memory reclaim
sparseVhd=true             # Automatic disk space reclaim

WSL Management Commands

Frequently used WSL management commands.

# Check WSL status
wsl --status

# Check running distros
wsl --list --running

# Shut down WSL (all distros)
wsl --shutdown

# Terminate a specific distro
wsl --terminate Ubuntu

# Update WSL
wsl --update

# Unregister a distro (caution: deletes all data)
wsl --unregister Ubuntu-24.04

Summary

WSL2 is the most efficient way to set up a Linux development environment on Windows. Key takeaways:

  • Installation: Complete with a single wsl --install, ready to use after reboot
  • Distros: Run multiple distros simultaneously, backup via export/import
  • VS Code integration: Edit WSL projects directly in VS Code with the code . command
  • Filesystem: Keeping projects on the WSL filesystem (~/) is better for performance
  • Resource management: Control memory, CPU, and swap size with .wslconfig

The combination of WSL2 and VS Code provides the most seamless cross-platform development experience on Windows.

Was this article helpful?