Local AI on Windows

02. WSL2 Installation and Configuration

Chapter 2 of 15 · 20 min

WSL2 requires Windows 10 version 2004 or later, or Windows 11. Run winver in Run to check your build number. Windows 11 22H2 or later is strongly recommended because it includes WSL2 GPU scheduler improvements that reduce latency for inference workloads.

Installation in an elevated PowerShell prompt:

wsl --install

This installs the WSL2 kernel, Ubuntu as the default distribution, and the Docker Desktop integration layer. After reboot, Ubuntu launches and prompts you to create a Linux username and password. These are separate from your Windows credentials—WSL2 has its own user database.

Verify the installation:

wsl.exe -l -v
# NAME                   STATE           VERSION
# Ubuntu                 Running         2
# docker-desktop         Stopped         2
# docker-desktop-data    Stopped         2

The VERSION column must show 2 for WSL2. Version 1 is an older architecture without GPU passthrough. If you see 1, convert the distribution:

wsl.exe --set-version Ubuntu 2

Common failure: wsl --install hangs on "Installing: WSL2 kernel update package" if Windows Update is blocked or if the machine is on a metered connection. Workaround: download the WSL2 kernel update MSI manually from Microsoft's catalog and install it with msiexec /i wsl_update_x64.msi.

Once installed, update the system and install core utilities:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git build-essential htop net-tools

Set a default working directory so new WSL2 terminals open somewhere sensible:

echo "cd /mnt/c/Users/YOUR_USERNAME" >> ~/.bashrc

Replace YOUR_USERNAME with your actual Windows username. The /mnt/c path maps to C:\ inside WSL2.

Local verification checkpoint

Run the smallest example from this chapter in a local workspace and record the package version, runtime, data path, and observed output. If the result depends on model size, vector count, CPU/GPU backend, or available memory, note that constraint beside the exercise so the lesson remains reproducible.

EXERCISE

Create a file inside WSL2 at ~/test.txt, verify it exists from Windows at \\wsl$\Ubuntu\home\youruser\test.txt, then delete it from both sides. This confirms the cross-filesystem link is working.