Set up WSL2

Set up a Wallabi development environment on Windows using WSL2.

This guide takes a Windows machine from any starting state (no WSL, partial WSL, or a fully working WSL2 install) to a configuration that is ready to get started. If part of your setup already exists, nothing here deletes or reinstalls an existing distro.

System requirements

  • 16 GB RAM or more
  • an SSD (not a mechanical drive)
  • a modern quad-core or better CPU
  • Local admin rights (needed only for a first-time WSL install)

This floor is real. Below it the dev server and file watchers underperform and no amount of tuning compensates. Codespaces + VS Code is the better option on that hardware.

What a good setup looks like

Four details define a healthy WSL2 setup, and they’re easy to get wrong.

  1. The project lives on the Linux filesystem (e.g. ~/projects), never under /mnt/c/. Crossing the 9p boundary on every file read makes installs and file watching much slower.
  2. Windows PATH interop is off. Leaking Windows executables into the Linux shell can cause confusing, hard-to-diagnose tooling failures.
  3. Your Ubuntu is the default distro, not Docker. Docker Desktop and similar tools sometimes register themselves as the default WSL distro, which sends your commands to the wrong environment.
  4. The vhdx isn’t scanned or synced. Repeatedly scanning or syncing the Ubuntu ext4.vhdx slows the filesystem, which drags on installs and dev server interactivity. Excluding it from OneDrive sync and Windows Defender scans is optional tuning. Try it if installs or the dev server feel slow.

Where to run these commands

This guide moves between two different shells, and it matters which one you’re in:

  • PowerShell is the Windows side. Open it from the Start menu by searching for “PowerShell”. Its prompt looks like PS C:\Users\You>. A first-time WSL install needs an administrator PowerShell (right-click, then Run as administrator); everything else here runs in a normal one.
  • WSL is the Linux side: a full Ubuntu shell running on the same machine. Once it’s installed, open one by typing wsl in PowerShell, or by launching Ubuntu from the Start menu. Its prompt looks like you@machine:~$. Type exit to go back to PowerShell.

The two have separate filesystems and separate installed tools: Node installed in WSL doesn’t exist in PowerShell, and vice versa. That separation is the point, and it’s what makes the Linux side fast, but it means a command run in the wrong shell will either fail or quietly do the wrong thing.

Every code block below says which shell it belongs to. If a command isn’t found, check your prompt first.

Assess what’s already there

Don’t assume a clean slate. From PowerShell:

wsl --status
wsl -l -v
What you seeWhat to do
wsl --status errors / nothing installedInstall WSL2 and a distro.
WSL present, but wsl -l -v lists only docker-desktop or nothingInstall a distro; you can skip the platform-enable prompt.
WSL + a working Ubuntu already listedSkip the install entirely. Go to Confirm the default distro. The rest of this guide only adds configuration, so do not reinstall or reset.

Install WSL2 and a distro (only if missing)

If WSL isn’t installed at all, this step turns on the underlying Windows features, which needs an administrator PowerShell: find PowerShell in the Start menu, right-click, and choose Run as administrator. If WSL is already there and you’re only adding a distro, a normal PowerShell is fine.

wsl --install -d Ubuntu-24.04
wsl --set-default-version 2

If you see The requested operation requires elevation, re-run it from an administrator PowerShell.

Reboot if prompted. Ubuntu then launches on first run and asks you to create a Linux username and password. These are separate from your Windows account, and the password is what sudo asks for later. Once that’s done you’re sitting in a WSL shell. This is the “inside WSL” the sections below refer to.

Confirm the default distro is your Ubuntu

Docker Desktop (or another tool) can register a WSL distro and quietly become the default, so plain wsl lands in the wrong environment. This fix only changes which distro is default. It deletes nothing.

From PowerShell:

wsl -l -v            # the * marks the current default
wsl --set-default Ubuntu-24.04

Disable Windows PATH interop

By default WSL appends the Windows PATH into the Linux shell, leaking Windows executables (node.exe, npm.cmd, etc.) into your Linux environment. Turn it off.

This edits /etc/wsl.conf, which may already exist and contain settings you want to keep, so merge, don’t overwrite. Inside WSL:

cat /etc/wsl.conf 2>/dev/null   # see what's already there

Ensure the file contains the following. If an [interop] section already exists, just add the one line; leave any existing [boot]/systemd lines untouched.

[interop]
appendWindowsPath=false

Then from PowerShell:

wsl --shutdown

Reopen WSL and verify nothing Windows-side remains on PATH:

echo "$PATH" | tr ':' '\n' | grep -i '/mnt/c' || echo "clean"

Should print clean.

Install Node and pnpm (inside WSL)

Install into the Linux environment. Never reuse a Windows Node. Inside WSL:

sudo apt update && sudo apt install -y curl git
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
exec bash
nvm install 22
corepack enable

Confirm you’re using the Linux Node, not a leaked Windows one:

which node    # should be under ~/.nvm/, not /mnt/c/...

VS Code

Install VS Code on Windows (not inside WSL), then add the WSL extension.

From any directory inside WSL, open it in VS Code with:

code .

This opens a remote window with the editor’s server component running Linux-side, so it operates directly on the Linux filesystem instead of reaching across the boundary. You’ll use this on your app host folder once you’ve cloned it.

Claude Code

Install with the native installer inside WSL:

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Complete the browser login when prompted. Launch it from the WSL terminal, not PowerShell.

End-state check

From PowerShell:

wsl -l -v            # Ubuntu is default (*), VERSION 2

Inside WSL:

echo "$PATH" | grep /mnt/c || echo ok   # ok
node -v                                 # v22.x
claude doctor

Next Steps

Your environment is ready. Continue with Getting Started to clone your app host and run your first app.

Run every command there in your WSL terminal, and clone into your WSL home directory (e.g. ~/projects). Never under /mnt/c/.

Once that guide is done you’ll have the dev server running in one pane and claude in another.