WSL Primer — How It Works, Basic Operations, and Real-World Pitfalls

A guide to WSL (Windows Subsystem for Linux) — running Linux on Windows — from how it works to the things you will actually need in practice. For background on shells and the relationship with Linux, see the terminal primer.

What is WSL?

An official Windows feature that runs a real Linux (a distribution such as Ubuntu) inside Windows. The current generation, WSL2, runs a genuine Linux kernel in a lightweight virtual machine, so Docker and server-side tools behave exactly as they do on real Linux.

• Where Git Bash is "an imitation of Unix-style commands," WSL is an actual Linux environment
• It starts instantly (no VM-style OS boot wait). Entering Linux feels like opening another terminal tab
• Windows apps and Linux apps run side by side on the same machine. The classic split: editor on the Windows side, runtime on the Linux side

The older WSL1 was a kernel-less compatibility layer; today you want WSL2, full stop (wsl -l -v tells you which one you have).

Installation

One command in an administrator PowerShell:

wsl --install

• Ubuntu is installed by default. For another distribution use wsl --install -d Debian (list them with wsl -l -o)
• On first launch you choose a Linux-side username and password. That password is what sudo (admin commands) asks for, so don't forget it
• On a company PC, WSL won't run if virtualization support (Intel VT-x etc.) is disabled in BIOS. Enabling it may require admin rights or an IT request

After installing, "Ubuntu" appears in Windows Terminal's dropdown — that is the easiest way in.

Basic wsl commands

Management commands used from the Windows side (PowerShell etc.):

Leave Linux with exit. Note that wsl --shutdown also takes down WSL-based tools like Docker Desktop, so time it thoughtfully.

Which side do your files go on? (Most important)

Windows and Linux have separate file systems, with passages between them:

• Linux → Windows files: /mnt/c/Users/NAME/...
• Windows → Linux files: \\wsl.localhost\Ubuntu\home\NAME\... in Explorer (also reachable from the "Linux" sidebar entry)

And the single most important rule in practice:

Keep projects on the Linux side (under ~/). Do not work under /mnt/c/.

File access through /mnt/c/ is inherently very slow — npm install and git operations can be several times to dozens of times slower. Almost every "WSL made everything slow" complaint traces back to this. Clone repositories inside WSL and keep them on the Linux side, e.g. /home/NAME/projects/....

VS Code integration

Install the "WSL" extension in VS Code and you get the ideal split: editor on Windows, files and runtime on Linux.

# from your project folder inside WSL
code .

This opens VS Code on the Windows side with "WSL: Ubuntu" in the lower-left corner. The terminal and debugger both run on the Linux side, so environment mismatches disappear. Extensions are managed separately for "Windows" and "WSL" — language extensions need to be installed on the WSL side too (VS Code prompts you).

Setting up a dev environment

The standard first steps once you are inside Ubuntu:

sudo apt update && sudo apt upgrade -y   # bring packages up to date
git --version                            # git is usually preinstalled
git config --global user.name "NAME"
git config --global user.email "EMAIL"

Do not install Node.js straight from apt (you get an old version). Use a version manager such as nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# reopen the shell, then
nvm install --lts

Caution: even if Node.js is installed on Windows, install a separate Node inside WSL. WSL's PATH also exposes Windows-side commands, so if which node points to /mnt/c/... you are picking up the Windows one (slow, and behaviors get mixed). Installing on the WSL side makes it take precedence.

Crossing between Windows and Linux

The delightful part of WSL — both sides can call each other:

# from inside WSL
explorer.exe .          # open the current folder in Explorer
clip.exe < file.txt     # copy to the Windows clipboard

# from the Windows side
wsl ls -la              # run a WSL command one-off

localhost is shared too. A dev server started inside WSL (say pnpm dev on localhost:3000) is reachable from a Windows browser at http://localhost:3000 as-is. Occasionally this forwarding breaks; wsl --shutdown and a restart fixes it.

Common real-world pitfalls

• Memory creep: Task Manager shows vmmem eating gigabytes. Cap it in %UserProfile%\.wslconfig on the Windows side, then apply with wsl --shutdown

[wsl2]
memory=8GB
processors=4

• Corporate proxies: traffic from inside WSL (apt / git / npm) may each need proxy settings. Targets: http_proxy / https_proxy env vars in ~/.bashrc, git config --global http.proxy, npm config set proxy. If your company uses an internal CA certificate, install it on the Linux side too (/usr/local/share/ca-certificates/ → sudo update-ca-certificates)
• Clock drift after sleep: the Linux clock occasionally drifts and causes TLS errors and the like. sudo hwclock -s or wsl --shutdown fixes it
• Line endings: files created on Windows are CRLF while Linux tools expect LF. Inside WSL, set git's core.autocrlf to input to stay safe
• When things are just weird: wsl --shutdown, then reopen. Restarting WSL takes seconds, so do it freely

Summary

• WSL2 = a real Linux running inside Windows. Editor on Windows, runtime on Linux is the standard split
• For management, wsl -l -v / wsl --shutdown / wsl --update cover almost everything
• Keep projects on the Linux side. Working under /mnt/c/ is slow (the number one rule)
• Use the VS Code WSL extension and code .. Install Node inside WSL with nvm
• localhost is shared. When in doubt, wsl --shutdown