Skip to content
WSL2 Cheat/sheet

Set up a new machine

From a fresh Windows 11 install to a project running in WSL, in six steps. About 45 minutes, most of it downloads.

Do these in order: each step only uses what the steps before it installed. Tick them off as you go; ticks are saved in this browser only.

You need Windows 11 (or Windows 10 22H2), an administrator account, and virtualisation enabled in the BIOS/UEFI (it usually is).

  1. Install and update WSL#

    Open PowerShell as administrator (Start → type PowerShell → Run as administrator):

    PowerShell · AdminInstall WSL with Ubuntu
    wsl --install -d Ubuntu

    Reboot when asked. Ubuntu opens by itself afterwards and asks for a Linux username and password; they are separate from your Windows login and only used for sudo. Then, in a normal PowerShell:

    PowerShellUpdate WSL and check the version
    wsl --update
wsl -l -v      # Ubuntu, VERSION 2

  2. Update Ubuntu packages#

    Open Ubuntu from the Start menu (or Windows Terminal → Ubuntu). Everything from here runs inside it.

    WSLUpgrade packages and add build tools
    sudo apt update && sudo apt full-upgrade -y
sudo apt install -y build-essential git curl unzip

  3. Create a project directory on the Linux filesystem#

    Keep code in your Linux home, never under /mnt/c. Tools on the Linux disk run at native speed and file watchers work; on /mnt/c installs and builds are 5–20× slower and hot reload misses changes. Why, in detail.

    WSLYour code lives here
    mkdir -p ~/dev
cd ~/dev

    From Windows, the folder is at \\wsl.localhost\Ubuntu\home\<you>\dev in Explorer.

  4. Connect the Windows editor to WSL#

    Install VS Code (or Cursor) on Windows, then add the WSL extension (ms-vscode-remote.remote-wsl). Back in Ubuntu:

    WSLOpen the folder in VS Code, running against Linux
    cd ~/dev
code .

    The first run installs a small server inside Linux. The bottom-left corner should say WSL: Ubuntu. JetBrains, Cursor and Windows Terminal: Open a WSL project in your editor.

  5. Install your project's runtime and configure Git#

    Use a version manager, not apt install nodejs. mise handles Node, Python and most other runtimes, and switches versions per project:

    WSLInstall mise (bash, Ubuntu's default shell)
    curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
exec bash
mise use -g node@lts      # or python@3.13, go, java… whatever your project needs

    Then tell Git who you are, and keep line endings as LF:

    WSLGit identity and defaults
    git config --global user.name  "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input

    Private repositories need authentication: Connect Git to GitHub with SSH. More runtimes and pinning versions per project: Install runtimes with mise.

  6. Run a project and verify the setup#

    Clone your project into ~/dev and start it, or create a throwaway one:

    WSLA test project
    cd ~/dev
npm create vite@latest hello -- --template vanilla
cd hello && npm install && npm run dev

    Open the printed address (http://localhost:5173) in your Windows browser. Then check:

    • which node prints a path under ~/.local/share/mise, not /mnt/c/….
    • code . from the project opens with WSL: Ubuntu in the status bar.
    • Editing main.js reloads the page in the browser within a second.

    All three true: your baseline works. Something off? Fix a problem is ordered by symptom.

0 done

Optional next steps#

None of these are required. Pick what your work needs: