Tech Setup
Windows Setup

Setting Up WSL2 with Ubuntu on Windows 11: Dev Guide

Tech Setup6 min read
TS

Tech Setup

Reviewed August 1, 2026

Setting Up WSL2 with Ubuntu on Windows 11: Dev Guide

Introduction

For years, developing on Windows meant dealing with the POSIX-compatibility layer of Cygwin, running heavy VirtualBox instances, or accepting a disjointed developer experience. Windows Subsystem for Linux 2 (WSL2) changes the paradigm entirely. By running a lightweight, managed micro-utility virtual machine powered by a real Linux kernel directly inside Windows 11, WSL2 provides a native Linux environment without dual-booting or performance degradation.

For senior developers, DevOps engineers, and system architects working on cloud-native software, Docker containers, and modern web stacks, WSL2 is no longer just an alternative—it is the default environment for Windows-based development.

This guide walks you through setting up a production-ready WSL2 environment on Windows 11, optimized for high performance, seamless file I/O, and containerized workflows.

Prerequisites and System Requirements

Before initializing WSL2, ensure your Windows 11 machine meets the baseline hardware and virtualization requirements.

Hardware & OS Requirements

  • Operating System: Windows 11 (Home, Pro, Enterprise, or Education) build 22000 or higher.
  • Processor: 64-bit CPU with Second Level Address Translation (SLAT) and hardware virtualization enabled in the BIOS/UEFI.

Verifying Virtualization

Open PowerShell as Administrator and run the following command to check if virtualization is enabled:

Get-ComputerInfo | Select-Object BiosFirmwareType, HyperVRequirementVirtualizationFirmwareEnabled

If HyperVRequirementVirtualizationFirmwareEnabled returns False, reboot your machine, enter your BIOS/UEFI settings, and enable Intel VT-x or AMD-V.

Installing WSL2 and Ubuntu

Microsoft has streamlined the installation process significantly. You no longer need to manually enable individual Windows features or download manual kernel update packages.

The One-Command Installation

Open PowerShell or Windows Terminal as Administrator. Right-click the Start menu and select Terminal (Admin).

Execute the default installation command:

wsl --install

This command performs the following actions automatically:

  1. Enables the Virtual Machine Platform and Windows Subsystem for Linux optional features.
  2. Downloads and installs the latest Linux kernel.
  3. Sets WSL 2 as the default architecture.
  4. Downloads and installs the default Linux distribution (Ubuntu).

Handling Custom Distributions

If you prefer a specific Ubuntu LTS release (e.g., Ubuntu 24.04 LTS) rather than the default, you can list available distributions and install them explicitly:

# List online available distributions
wsl --list --online

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

Once the installation completes, restart your computer to finalize the system changes.

Initializing Ubuntu

After rebooting, a terminal window will automatically launch, prompting you to complete the Ubuntu installation.

  1. Wait for the installation scripts to unpack.
  2. Enter a UNIX username (this does not need to match your Windows username).
  3. Enter and confirm a password (typed characters will not be displayed).

You are now greeted with a native Bash shell running inside Ubuntu on WSL2.

Verifying and Upgrading to WSL2

If you upgraded an existing Windows installation, your distribution might occasionally default to WSL version 1. Let's verify and enforce WSL2.

Check Current Versions

In PowerShell, run:

wsl --list --verbose

You should see output similar to this:

  NAME            STATE           VERSION
* Ubuntu-24.04      Running         2

If the VERSION column reads 1, convert the distribution to WSL2 immediately:

wsl --set-version Ubuntu-24.04 2

To ensure that any future distributions you install default to WSL2 automatically, set the global default version:

wsl --set-default-version 2

Configuring the WSL2 Environment for Performance

Out-of-the-box WSL2 is functional, but senior developers need it tuned for peak performance, smooth networking, and seamless cross-OS operations.

Understanding the .wslconfig File

WSL2 allows global configuration through a .wslconfig file placed in your Windows user profile directory (C:\Users\YourUsername\.wslconfig). This file dictates resource allocation, memory limits, and networking behavior for the underlying utility VM.

Create or open C:\Users\YourUsername\.wslconfig in your editor of choice (e.g., VS Code) and add the following production-grade configuration:

[wsl2]
# Assign up to 8GB of RAM (adjust based on your machine's total RAM)
memory=8GB

# Limit the VM to use half of your logical CPU cores
processors=4

# Enable nested virtualization for Docker/Kubernetes testing
nestedVirtualization=true

# Enable localhost forwarding so ports bound in Linux are accessible on Windows via localhost
localhostForwarding=true

# Use mirrored networking mode for better VPN and local network compatibility (Windows 11 build 22621+)
networkingMode=mirrored

Save the file. To apply these changes, restart WSL by running the following command in PowerShell:

wsl --shutdown

File System Architecture & Optimization

One of the most critical performance pitfalls in WSL2 development is file I/O cross-contamination.

The Golden Rule of WSL2 File I/O

  • Fast: Code repositories stored inside the Linux ext4 file system (/home/username/projects).
  • Slow: Code repositories stored on the Windows NTFS file system accessed via the 9P protocol (/mnt/c/projects).

File system operations (like git status, npm install, or webpack builds) run up to 20x faster when executed entirely within the Linux file system.

Best Practices

  1. Never clone Git repositories directly to /mnt/c/... for heavy development.
  2. Open your Ubuntu terminal and create your workspace inside the Linux home directory: 
    mkdir -p ~/projects
cd ~/projects
  3. Access your Linux files from Windows Explorer without risking performance degradation by typing \\wsl$ in the Windows File Explorer address bar.

Integrating with Windows Developer Tools

WSL2 does not require you to abandon the graphical Windows tools you love. Modern IDEs bridge the gap seamlessly.

Visual Studio Code Integration

VS Code offers first-class support for WSL via the WSL extension.

  1. Open VS Code on Windows.
  2. Navigate to the Extensions view (Ctrl+Shift+X) and search for WSL (published by Microsoft) and install it.
  3. Open your Ubuntu terminal, navigate to your project directory, and launch VS Code directly into the WSL context: 
    cd ~/projects/my-app
code .
  4. A new VS Code window will open with [WSL: Ubuntu] clearly indicated in the bottom-left corner. All terminal commands, extensions, and debuggers will now run directly inside the Linux container.

Git Credentials and SSH Keys

To avoid managing separate SSH keys on Windows and Linux, you can share your existing Windows SSH credentials with WSL, or generate a dedicated key inside WSL.

To symlink or copy your Windows Git configuration and SSH keys into Ubuntu, run the following commands inside your WSL terminal:

# Optional: Point Git to use Windows Credential Manager if sharing repos across OS boundaries
git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

For optimal performance and security, however, it is recommended to generate a native ED25519 SSH key inside WSL:

ssh-keygen -t ed25519 -C "developer@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Docker Integration and Containers

Running Docker natively inside WSL2 bypasses the legacy Docker Desktop architecture overhead if configured correctly, though Docker Desktop remains the simplest way to manage containers on Windows 11.

  1. Install Docker Desktop for Windows.
  2. During installation, ensure "Use the WSL 2 based engine" is checked.
  3. Open Docker Desktop settings -> Resources -> WSL Integration.
  4. Toggle on integration with your installed Ubuntu distribution.
  5. You can now run standard docker commands directly inside your Ubuntu WSL2 terminal.

Option B: Native Docker Engine inside WSL2 (Rootless/Systemd)

If you prefer running Docker entirely inside the Linux VM without Docker Desktop:

Ensure systemd is enabled in your distribution. Open /etc/wsl.conf inside Ubuntu:

[boot]
systemd=true

Restart WSL via wsl --shutdown from PowerShell, then run the standard Docker convenience script inside Ubuntu:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=\"$(dpkg --print-architecture)\" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group to run commands without sudo:

sudo usermod -aG docker $USER
newgrp docker

Essential Post-Setup Maintenance

To keep your WSL2 environment lean, perform routine maintenance and backups.

Managing Disk Space

By default, WSL2 uses a virtual hard disk (ext4.vhdx) that grows dynamically as you add files, but it does not automatically shrink when you delete files. This can lead to bloated disk usage on your Windows host.

To shrink the VHDX file:

  1. Shut down all WSL instances from PowerShell: 
    wsl --shutdown
  2. Open diskpart or use PowerShell to optimize the VHDX. Run PowerShell as Administrator: 
    Optimize-VHD -Path "C:\Users\YourUsername\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode Full
    (Note: Adjust the path to match your specific distribution's package folder name under AppData\Local\Packages).

Backing Up and Exporting Distributions

Before performing major system updates, export your distribution as a tarball:

wsl --export Ubuntu-24.04 C:\backups\ubuntu-backup.tar

To restore or duplicate the distribution on another machine:

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

Conclusion

You now have a fully operational, high-performance WSL2 environment running Ubuntu on Windows 11. By storing your codebase inside the native Linux file system, tuning resource limits via .wslconfig, and integrating with VS Code and Docker, you get the best of both worlds: the robust hardware and peripheral support of Windows paired with the robust, cloud-aligned ecosystem of Linux.

Related articles