Claude Code Windows WSL2 Setup Guide

Claude Code does not run natively on Windows. It is built for Linux and macOS environments, and requires WSL2 (Windows Subsystem for Linux) to run on Windows machines. WSL2 gives you a real Linux kernel running inside Windows, which is where Claude Code and Node.js will actually execute.

This guide covers every step from a standard Windows 11 or Windows 10 machine to a working Claude Code session connected to VS Code.

Why WSL2 Is Required

Claude Code relies on POSIX-compatible shell behavior, Unix file paths, and Linux-native npm package execution. The Windows Command Prompt and PowerShell do not provide these. WSL2 runs a full Linux kernel as a lightweight virtual machine, which means Claude Code runs exactly as it does on a native Linux machine, with full compatibility.

WSL1 (the older version) uses a compatibility layer rather than a real kernel, and causes subtle errors with Claude Code. Use WSL2 specifically.

WSL2 is not a workaround. It is the supported path for Windows users. Anthropic does not provide a native Windows build of Claude Code.

Step 1: Enable WSL2

Open PowerShell as Administrator. Right-click the Start button, select “Windows PowerShell (Admin)” or “Terminal (Admin)”.

Run:

wsl --install

This single command enables the WSL feature, installs the WSL2 kernel, and installs Ubuntu as the default distribution. It requires a restart to complete.

If your system already has WSL installed but is running WSL1, upgrade to WSL2:

wsl --set-default-version 2

To verify your WSL version after restart:

wsl --list --verbose

Look for VERSION 2 next to your Ubuntu distribution. Windows 10 version 2004 (build 19041) or higher is required. Windows 11 supports WSL2 on all versions.

Step 2: Install Ubuntu from the Microsoft Store

The wsl --install command installs Ubuntu by default. If you want to confirm or install manually, open the Microsoft Store, search for “Ubuntu”, and install “Ubuntu 22.04 LTS” or “Ubuntu 24.04 LTS”. Both are fully supported.

After installation, launch Ubuntu from the Start menu. The first launch takes a minute to complete initial setup. You will be prompted to create a Linux username and password. This username does not need to match your Windows username.

Once the Ubuntu prompt appears (it looks like yourname@machinename:~$), you are inside the WSL2 Linux environment. All subsequent steps in this guide run inside this Ubuntu terminal.

Step 3: Install nvm Inside Ubuntu

nvm (Node Version Manager) is the recommended way to install Node.js inside WSL2. It installs Node in your Linux home directory and avoids permission issues with global npm installs.

Inside your Ubuntu terminal, run:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

After the install script completes, close and reopen your Ubuntu terminal, or reload your shell configuration:

source ~/.bashrc

Verify nvm is active:

nvm --version

Step 4: Install Node 20 LTS

Install Node.js 20 LTS and set it as default:

nvm install 20
nvm use 20
nvm alias default 20

Confirm the active version:

node --version
# Should output v20.x.x
npm --version

Claude Code requires Node 18 or higher. Node 20 LTS is recommended because it has the longest active support window.

Step 5: Install Claude Code

With Node 20 active, install Claude Code globally:

npm install -g @anthropic-ai/claude-code

Verify the installation:

claude --version

If claude is not found after install, your npm global bin directory may not be in your PATH. nvm handles this automatically in most cases, but if you see an error, run:

export PATH="$PATH:$(npm config get prefix)/bin"
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

Step 6: Authentication Setup in WSL2

Set your Anthropic API key as an environment variable inside WSL2. Add it to ~/.bashrc so it persists across sessions:

echo 'export ANTHROPIC_API_KEY=your_api_key_here' >> ~/.bashrc
source ~/.bashrc

Get your API key from console.anthropic.com under API Keys.

Alternatively, if you use a Claude Max subscription, authenticate via the browser OAuth flow:

claude auth login

This opens a browser on the Windows side and completes authentication. The token is stored in your WSL2 Linux home directory. For a comparison of both authentication methods, see Claude Code authentication setup.

Step 7: Connect VS Code to WSL2

VS Code has built-in support for WSL2 development via the Remote Development extension pack. This lets you open your Linux filesystem in VS Code, run the VS Code integrated terminal inside WSL2, and use all VS Code extensions in the Linux environment.

Install the extension:

1. Open VS Code on Windows
2. Press Ctrl+Shift+X to open Extensions
3. Search for “Remote - WSL” (published by Microsoft)
4. Click Install

Once installed, connect to WSL2 from VS Code:

• Press Ctrl+Shift+P, type WSL: Connect to WSL, and press Enter
• Or, inside your Ubuntu terminal, navigate to your project directory and run: code .

The code . command opens VS Code on Windows with the current WSL2 directory as the workspace. The VS Code integrated terminal (Ctrl+\``) opens directly in the WSL2 Ubuntu shell, where you can run claude` normally.

Accessing Windows Files from WSL2

Your Windows drives are mounted in WSL2 under /mnt/. Your C drive is at /mnt/c/.

To navigate to a project on your Windows Desktop:

cd /mnt/c/Users/YourWindowsUsername/Desktop/your-project

You can run Claude Code from any directory inside /mnt/c/ or from your Linux home directory (~/). For projects you work on frequently, storing them in the Linux home directory (~/projects/) gives better performance because WSL2 file I/O is faster on the Linux filesystem than on the mounted Windows filesystem.

Common WSL2 Errors and Fixes

FAQ

Do I need Windows 11 for WSL2?

No. WSL2 is available on Windows 10 version 2004 (build 19041) and higher. Windows 11 supports WSL2 on all versions. Run winver in PowerShell to check your Windows version.

Can I run Claude Code on Windows without WSL2?

No. Claude Code requires a POSIX-compatible shell environment. It does not run in Command Prompt, PowerShell, or Git Bash. WSL2 is the only supported Windows path.

Should I store my projects in WSL2 or in Windows?

For projects you use with Claude Code regularly, store them inside the WSL2 Linux filesystem (for example, ~/projects/). File I/O from WSL2 to the Linux filesystem is significantly faster than file I/O through the /mnt/c/ mount. You can still open these files in Windows Explorer by navigating to \\wsl$\Ubuntu\home\yourusername\projects\ in the address bar.

What Ubuntu version should I install?

Ubuntu 22.04 LTS and Ubuntu 24.04 LTS are both supported. Ubuntu 22.04 LTS (Jammy) has the broadest compatibility with existing Node.js tooling. Ubuntu 24.04 LTS (Noble) is newer and will be supported until 2029. Either works correctly for Claude Code.

Phos AI Labs is a CCA-F certified Claude implementation partner with 400+ engagements. If your development team is rolling out Claude Code across mixed Mac and Windows environments, contact us to discuss standardized setup, authentication patterns, and CLAUDE.md templates that work across both platforms.