WSL: Run Linux on Windows

Windows Subsystem for Linux 2 (WSL2) gives you a real Linux kernel running inside a lightweight Hyper-V virtual machine, tightly integrated with Windows. You get a full bash shell, native Linux binaries, and access to both filesystems — without a dual-boot partition or a separate VM. This guide walks through installation, picking a distro, moving files between Windows and Linux, and enabling systemd so you can manage services the modern way.

Prerequisites

• Windows 10 version 2004 (Build 19041) or later, or Windows 11. Run winver to check.
• Virtualization enabled in UEFI/BIOS firmware (usually on by default on modern hardware).
• Administrator access to your Windows account.

Installing WSL2

Microsoft ships a single command that installs the WSL platform, downloads a kernel update, sets WSL2 as the default, and pulls a default distro (Ubuntu). Open PowerShell or Windows Terminal as Administrator.

wsl --install

Reboot when prompted. After the reboot, Ubuntu will finish installing and ask you to create a UNIX username and password. These credentials are independent of your Windows account.

If WSL was already partially installed and you just need to ensure WSL2 is the default version:

wsl --set-default-version 2

Verify the installation

After setup, confirm the running version from PowerShell:

wsl --list --verbose

Output will look something like:

  NAME      STATE           VERSION
* Ubuntu    Running         2

The VERSION column must show 2. If it shows 1, convert it:

wsl --set-version Ubuntu 2

Choosing and Installing a Distro

Ubuntu is the default, but WSL supports many distributions. List what is available in the Microsoft Store catalog directly from the command line:

wsl --list --online

Install any distro by name:

# Debian
wsl --install -d Debian

# Fedora (community-maintained via a separate inbox)
# For Fedora you typically use the Fedora WSL image from the Store or GitHub

# Arch Linux via a community project such as ArchWSL
# https://github.com/yuk7/ArchWSL

You can run multiple distros side by side. Set one as your default launch target:

wsl --set-default Debian

To launch a specific distro without changing the default:

wsl -d Debian

First steps inside the distro

Once inside your Linux shell, update the package index and apply any pending upgrades immediately — WSL images are often slightly out of date.

# Debian / Ubuntu
sudo apt update && sudo apt upgrade -y

# Fedora
sudo dnf upgrade -y

# Arch
sudo pacman -Syu

Accessing Files Between Windows and Linux

Reaching Windows files from Linux

WSL automatically mounts your Windows drives under /mnt/. Your C: drive is at /mnt/c.

ls /mnt/c/Users/YourWindowsUsername/Documents

You can read, write, and execute files here just like any Linux path. Be aware that Windows NTFS paths are case-insensitive; Linux treats case as significant, so keep filenames consistent.

Reaching Linux files from Windows

Every WSL distro exposes its Linux filesystem over a network path. In Windows Explorer, navigate to:

\\wsl$\Ubuntu\home\yourusername

Or type \\wsl$ in the Explorer address bar to see all running distros. You can pin these paths as Quick Access shortcuts.

Important: Do not use Windows tools (Notepad, VS Code on the Windows side without the WSL extension, Explorer copy operations) to modify files that live inside the Linux filesystem (\\wsl$\...) if those files have Linux permissions that matter. Prefer editing from within the Linux shell, or use the VS Code WSL extension which routes everything through the Linux side correctly.

Performance tip: keep project files on the right side

Cross-filesystem I/O has overhead. If you are doing Linux-heavy work (compilation, git, Node modules), keep source files under your Linux home directory (~/), not under /mnt/c. Windows tools like Explorer or browsers can still reach them via \\wsl$, but the Linux kernel handles all the heavy I/O natively.

Enabling systemd in WSL

WSL2 supports systemd as PID 1, but it must be explicitly enabled. Without it, services like sshd, docker, or postgresql cannot be managed with systemctl. This feature requires WSL version 0.67.6 or later.

Check your WSL version

From PowerShell:

wsl --version

If the command is not found, update WSL:

wsl --update

Enable systemd

Inside your Linux distro, create or edit the WSL configuration file:

sudo nano /etc/wsl.conf

Add the following block:

[boot]
systemd=true

Save the file, then shut down the WSL instance from PowerShell so the change takes effect on the next launch:

wsl --shutdown

Reopen your distro. Verify systemd is running:

systemctl list-units --type=service --state=running

If you see a list of active services, systemd is working. You can now enable and start units normally:

sudo systemctl enable --now ssh

Useful WSL Configuration Options

Beyond systemd, /etc/wsl.conf controls several behaviours. A practical starting configuration:

[boot]
systemd=true

[user]
default=yourusername

[interop]
appendWindowsPath=true

[automount]
enabled=true
options="metadata,umask=22,fmask=11"

The metadata option under [automount] allows Linux permission bits to be stored on NTFS volumes, which prevents every file under /mnt/c from appearing executable.

Troubleshooting

WSL command not found after reboot

Run Windows Update. WSL2 with the built-in kernel ships as a Windows component and sometimes needs an update pass to fully activate.

Distro stuck at "Installing" for minutes

Check that the Windows firewall or any security software is not blocking the Microsoft Store download. Alternatively, download the distro .appx package directly from Microsoft's manual install page and install it with Add-AppxPackage in PowerShell.

systemctl: Failed to connect to bus

This means systemd did not start as PID 1. Double-check /etc/wsl.conf has the correct syntax — the section header must be [boot] with a lowercase b, and there must be no stray characters. Run wsl --shutdown from PowerShell and relaunch.

Poor filesystem performance on /mnt/c

This is expected behaviour due to the Plan 9 filesystem protocol used to bridge the two kernels. Move active project directories into the Linux filesystem (~/projects for example) for dramatically better build and git performance.