WSL setup & distros

Starter Install a Linux distro on Windows and manage it from PowerShell.

Source of truth

Docs: learn.microsoft.com/windows/wsl
Written against: WSL 3.0.3 and Ubuntu 26.04 LTS on Windows 11. The install was run for real; the backup, move and remove commands come from wsl --help and weren't run.

Install

Check what's on offer, then install. Approve the admin prompt if Windows asks.

wsl --list --online
wsl --install Ubuntu-26.04

Plain wsl --install gives you the default distro. Add --no-launch to install now and create your account later. Reboot if the installer asks.

First run

wsl -d Ubuntu-26.04

Create a Linux username and password when asked. The password is separate from your Windows one, and nothing appears on screen as you type it.

Then update the packages:

sudo apt update && sudo apt upgrade -y

Everyday commands

Run these from PowerShell.

Command	What it does
wsl	Open the default distro
wsl -d NAME	Open a specific distro
wsl -d NAME -u root	Open it as root
wsl --cd ~	Start in your Linux home folder
wsl --list --verbose	List distros, their state and WSL version
wsl --status	Show the default distro and version
wsl --version	Show WSL and kernel versions
wsl --update	Update WSL itself
wsl --set-default NAME	Change the default distro
wsl --terminate NAME	Stop one distro
wsl --shutdown	Stop all distros and the WSL VM

Where to keep projects

Keep repos on the Linux side, like ~/projects. Tools run much faster there than against /mnt/c/....

From	To	Path
Linux	Windows drive	/mnt/c/Users/YOU
Windows	Linux files	\\wsl.localhost\Ubuntu-26.04\home\YOU
Linux	Open this folder in Windows	explorer.exe .
Linux	Open this folder in VS Code	code .

More in Paths & DDEV.

Limit memory and CPU

Create %USERPROFILE%\.wslconfig on Windows:

[wsl2]
memory=16GB
processors=8

Then restart WSL:

wsl --shutdown

This file doesn't apply to WSL containers. They use settings.yaml.

Back up, move or remove

# Back up a distro to one file
wsl --export Ubuntu-26.04 ubuntu-backup.tar

# Restore it under a new name and location
wsl --import Ubuntu-Restored D:\wsl\ubuntu-restored ubuntu-backup.tar

# Move a distro to another drive
wsl --manage Ubuntu-26.04 --move D:\wsl\ubuntu

Permanent

wsl --unregister NAME deletes the distro and all its files, with no confirmation. Export first if you might need anything from it.

Desktop distros

WSL is built around the command line, so distros sold on their desktop lose most of their point here.

• Zorin OS: not in wsl --list --online. Use a VM to get the real desktop.
• Omarchy: built around the Hyprland desktop, which doesn't run under WSL. Use a spare disk or a VM.
• Plain Arch: archlinux is in the official list, without a desktop.

Security

A WSL distro is not a sandbox. By default it can read and write your Windows drives through /mnt/c, so a malicious install script inside WSL can reach your Windows files.

For a repo you don't trust, use a container with only the files it needs, or a disposable VM like Windows Sandbox.

Related

• WSLC containers
• SSH agent
• PowerShell