Back to Blog
December 3, 202518 min readArion Interactive Team

Setting up WSL on Windows 11: A Detailed Developer Guide

Step-by-step guide to install, configure, and optimize Windows Subsystem for Linux (WSL) on Windows 11 for development workflows.

WSLWindows 11LinuxDeveloper Setup
Setting up WSL on Windows 11: A Detailed Developer Guide

Windows Subsystem for Linux (WSL) lets you run a genuine Linux environment directly on Windows without the overhead of a VM. This guide walks through installing WSL on Windows 11, configuring a developer-friendly environment, integrating with Windows tools, and troubleshooting common issues.

Overview

This guide covers:

  • Installing WSL (including WSL 2) and choosing a Linux distribution
  • Configuring the distro for development (packages, shells, fonts)
  • Integrating with Windows tools (Windows Terminal, VS Code Remote - WSL)
  • Filesystem and performance considerations
  • Docker integration, GUI apps (WSLg), and common troubleshooting

1. Prerequisites

  • Windows 11 with the latest updates installed
  • Administrative access to enable Windows features (if needed)
  • Windows Terminal (recommended) and a modern code editor (VS Code)

2. Install WSL (simplest method)

On Windows 11 the easiest install is:

wsl --install

This command will:

  • Enable the required Windows features for WSL
  • Install the latest WSL kernel
  • Download and install the default Linux distribution (typically Ubuntu)
  • Configure WSL 2 as the default backend

If prompted, reboot. On first launch create your Linux user and password.

To install a specific distro (for example, Ubuntu 22.04):

wsl --install -d ubuntu-22.04

List available distributions:

wsl --list --online

3. Verify WSL version and status

Check installed distros, versions, and WSL status:

wsl --list --verbose
wsl --status

If a distro is on WSL 1, convert it to WSL 2:

wsl --set-version <distro-name> 2

Set WSL 2 as the default for future installs:

wsl --set-default-version 2

4. Update the WSL kernel (if needed)

If Windows requests a kernel update, follow the Microsoft instructions and then run:

wsl --update
wsl --shutdown

Re-launch your distro after the update.

5. Windows Terminal and WSLg (GUI) support

Install Windows Terminal from the Microsoft Store for a modern terminal experience. Windows 11 builds include WSLg (GUI app support) by default; run wsl --update to get the latest capabilities.

6. Basic distro setup

Open your distro (e.g., Ubuntu) and update packages:

sudo apt update && sudo apt upgrade -y

# Essential build tools
sudo apt install -y build-essential curl git ca-certificates gnupg lsb-release

# Recommended developer tools
sudo apt install -y zsh htop fd-find ripgrep tree

Consider installing zsh and oh-my-zsh for an improved shell experience.

7. Configure Git, SSH, and editor integration

Set your Git identity and preferred editor (VS Code example):

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global core.editor "code --wait"

Generate and add SSH keys:

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

Copy ~/.ssh/id_ed25519.pub to your Git host (GitHub/GitLab/Bitbucket).

8. Using VS Code with WSL

Install the Remote - WSL extension in VS Code. From WSL run:

code .

This opens the current folder in VS Code with the server running inside WSL for seamless editing, debugging, and terminal integration. Install language servers and linters inside WSL for best results.

9. Filesystem and performance tips

  • Store active projects inside the Linux filesystem (for example ~/projects) — working across /mnt/c can be significantly slower for frequent I/O.
  • Access Windows files from WSL via /mnt/c/... when necessary.
  • From Windows Explorer you can browse the distro filesystem at \wsl$<distro-name>.

10. Docker and containers

For container-based development use Docker Desktop for Windows configured to use the WSL 2 backend. In Docker Desktop enable integration with your distro (Settings → Resources → WSL Integration). Alternatively, run Docker inside WSL distributions and use docker context to switch contexts.

11. GUI apps (WSLg)

If WSLg is available, you can run Linux GUI apps with clipboard and audio integration:

sudo apt install -y gedit
gedit &

12. Networking and localhost

WSL 2 runs in a lightweight VM and recent Windows builds forward localhost between Windows and WSL. Services started in WSL are usually accessible from Windows as http://localhost:PORT. If networking behaves unexpectedly, try:

wsl --shutdown

then restart your distro.

13. Common troubleshooting

  • Kernel update required: wsl --update then wsl --shutdown
  • Distro not starting: check wsl --list --verbose
  • Convert distro versions: wsl --set-version <distro-name> 2
  • Unregister a broken distro: wsl --unregister <distro-name> (this deletes the distro)
  • Slow filesystem performance: keep projects inside the Linux filesystem

14. Useful commands reference

# List distros and versions
wsl --list --verbose

# Show WSL status
wsl --status

# Set default distro/version
wsl --set-default <distro-name>
wsl --set-default-version 2

# Convert distro to WSL 2
wsl --set-version <distro-name> 2

# Update WSL components and kernel
wsl --update
wsl --shutdown

15. Recommendations

  • Use WSL 2 for full Linux kernel compatibility and best compatibility with Docker and GUI apps.
  • Keep your distro and WSL kernel updated.
  • Use VS Code Remote - WSL for best developer ergonomics.
  • Store active projects in the WSL filesystem to avoid I/O penalties.

With WSL set up you get native Linux tooling integrated into your Windows workflow, enabling reproducible and container-friendly development environments without the overhead of a full VM.