Claude Code on WSL2: Install, Speed Up, and Fix the Common Errors

To run Claude Code on WSL2, open your Linux distribution, run curl -fsSL https://claude.ai/install.sh | bash, and start claude from a project folder inside your Linux home directory. You don’t need Node.js, and you don’t need Git for Windows. Most of the problems people hit afterwards come from three places: the project lives on /mnt/c, the login browser doesn’t open, or Windows programs leak into the Linux PATH.

This guide covers the install, the one folder decision that makes Claude Code fast or slow, the sandbox (the main reason to pick WSL2 over native Windows), and an error index with the fix for each message. Commands and error texts follow the official Claude Code docs as of November 11, 2026, and every section links its source.

Quick Start: Claude Code on WSL2 in 5 minutes

In PowerShell, check that your distribution runs on WSL version 2:

wsl -l -v

Then open the distribution and run everything else inside the WSL terminal:

# 1. Install Claude Code (no Node.js needed)
curl -fsSL https://claude.ai/install.sh | bash

# 2. Open a NEW terminal tab, then confirm it works
claude --version

# 3. Keep projects in your Linux home, not on /mnt/c
mkdir -p ~/projects && cd ~/projects

# 4. Start Claude Code and log in
claude

If step 2 says claude: command not found, jump to the error index. If you don’t have WSL2 yet, start with Install WSL2 on Windows.

WSL2 or native Windows: which one should you pick?

Claude Code runs on Windows in three ways. The setup docs compare them like this:

The short version:

• Pick WSL2 if your project builds and runs on Linux (Node, Python, Docker, most web stacks), or if you want sandboxed commands. On a Windows machine, WSL2 is the only way to get the sandbox.
• Pick native Windows if the code has to stay on the Windows drive, for example .NET desktop apps, Unity projects or anything tied to Windows tools. Claude Code reading a Windows folder through WSL2 is the slow path, as the next sections show.
• Skip WSL1 unless you have no choice. There’s no sandbox, and current builds can fail with Exec format error.

You can install both. The WSL2 install and the Windows install are separate programs with separate settings folders.

Install Claude Code on WSL2 step by step

Step 1: Check the requirements

Claude Code needs Windows 10 version 1809 or later, a supported distribution such as Ubuntu 20.04+ or Debian 10+, and at least 4 GB of RAM. You also need a paid Claude plan (Pro, Max, Ultra, Team or Enterprise) or a Claude Console account. The free claude.ai plan doesn’t include Claude Code.

Confirm the WSL version from PowerShell:

wsl -l -v

The VERSION column should show 2 for your distribution. If it shows 1, convert it. Replace Ubuntu with the name from the list:

wsl --set-version Ubuntu 2

Step 2: Run the native installer inside WSL

Open your distribution and run the Linux installer there. Don’t run it from PowerShell or CMD, because that installs the Windows version instead:

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

The command shows no progress while it downloads. When it finishes, the program sits at ~/.local/bin/claude, which is a symlink into ~/.local/share/claude/versions/.

This is the recommended install method. It doesn’t use Node.js, it updates itself in the background, and it avoids the whole class of npm problems that WSL is known for. If an older guide told you to run npm install -g @anthropic-ai/claude-code, you can still do that, but the npm package now downloads the same native binary. On WSL the installer is the simpler path.

Step 3: Verify the install

Open a new terminal tab so the PATH change applies, then run:

claude --version
claude doctor

claude --version prints a version number followed by (Claude Code). claude doctor prints read-only diagnostics: install health, settings errors and the result of the last update.

Step 4: Log in

Go to a project folder and start Claude Code:

cd ~/projects/my-app
claude

Claude Code opens a login page in your Windows browser. Sign in, and the terminal continues on its own. On WSL2 this step fails more often than any other, usually because no browser opens. The fix takes ten seconds and is the third entry in the error index.

Keep your projects off /mnt/c

This is the decision that matters most for speed. A folder like /mnt/c/Users/you/code/my-app lives on the Windows drive, and WSL2 reaches it through a slower cross-system file layer. Claude Code searches and reads a lot of files, so it feels that cost on every turn.

The troubleshooting docs describe the symptom directly: on WSL, searching across file systems can return fewer matches than expected. Search still works, but it finds less, and claude doctor still shows Search as OK. So Claude may tell you a function isn’t used anywhere when it is.

Check where you are:

pwd

If the path starts with /mnt/, move the project. For a git repository, the cleanest way is a fresh clone into your Linux home:

mkdir -p ~/projects && cd ~/projects
git clone https://github.com/you/my-app.git
cd my-app

For a folder without a remote, copy it and leave the heavy generated folders behind. Install rsync first if your distribution doesn’t have it:

rsync -a --exclude node_modules --exclude .venv \
  /mnt/c/Users/you/code/my-app/ ~/projects/my-app/

Then reinstall dependencies inside WSL so they are built for Linux. You keep access from Windows: explorer.exe . opens the current Linux folder in File Explorer, and the same files show up under \\wsl.localhost\ in any Windows program.

If the project has to stay on the Windows drive, the docs suggest two things: ask for narrower searches (“find JWT validation in the auth-service package” instead of “find JWT validation”), or run Claude Code natively on Windows for that project.

My WSL2 performance guide explains why /mnt/c is slow and covers the .wslconfig limits that keep WSL2 from eating your RAM during long agent sessions.

Turn on the sandbox

The sandbox is what WSL2 gives you that native Windows can’t. On native Windows, Claude Code runs commands unsandboxed. On WSL2, it can run each Bash command inside a restricted environment, per the sandboxing docs:

• Writes are limited to the working directory, your temp directory and any folders you add.
• Network traffic goes through a proxy, and the command runs in its own network namespace.
• Reads still cover most of the machine, including ~/.ssh, unless you add denyRead rules.

Install the two packages it needs:

sudo apt-get install bubblewrap socat

Restart Claude Code, because the dependency check runs at startup. Then type:

/sandbox

Pick a mode in the panel. To turn the sandbox on for every project, set it in ~/.claude/settings.json:

{
  "sandbox": {
    "enabled": true
  }
}

Two WSL2 details are worth knowing before you rely on it:

• localhost is private to the sandboxed command. A sandboxed curl localhost:3000 doesn’t reach a dev server running outside the sandbox.
• Windows programs are a special case. WSL starts cmd.exe, powershell.exe and anything under /mnt/c/ through a Unix socket to the Windows host. Whether a sandboxed command can do that depends on the sandbox’s Unix socket settings, covered in the error index below.

Error index: messages and fixes

Find your message, apply the fix. Sources are the install troubleshooting, troubleshooting, sandboxing and JetBrains pages of the Claude Code docs.

bash: claude: command not found

The installer puts claude in ~/.local/bin but doesn’t change your PATH. First check that the program exists:

ls -la ~/.local/bin/claude

If you get a listing, add the folder to your PATH and reload the shell config:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

If you use Zsh, write to ~/.zshrc instead. If ls says No such file or directory, the install didn’t finish. Run the installer again and read its output.

Installing the VS Code extension doesn’t give you a claude command. The extension ships a private copy of the CLI for its own chat panel and doesn’t add it to PATH.

cannot execute binary file: Exec format error

Your distribution runs on WSL1, and the current binary hits a known loader problem there (issue #38788). Convert the distribution from PowerShell:

wsl --set-version Ubuntu 2

If you have to stay on WSL1, the docs give a workaround that starts the binary through the dynamic linker. Add this function to ~/.bashrc, then run source ~/.bashrc:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

The login browser doesn’t open, or shows a localhost error

Two versions of the same problem: nothing opens at all, or the browser signs you in and then shows a connection error for a localhost address. You can finish the login without fixing either one:

1. At the login prompt, press c to copy the login URL.
2. Paste it into your Windows browser and sign in. The page now shows a code.
3. Paste the code into the terminal at the Paste code here prompt.

If pasting does nothing, your terminal’s paste shortcut isn’t reaching the prompt. Try right-click or Shift+Insert in Windows Terminal. If that fails too, quit and run the login as its own command, which reads the code from standard input:

claude auth login

To make the browser open on its own next time, point the BROWSER variable at a Windows browser. Add this line to ~/.bashrc and adjust the path if you use a different browser:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"

An OAuth error: Invalid code message means the code expired or got cut off during copying. Press Enter to retry and paste faster.

exec: node: not found and npm platform errors

These only happen if you installed with npm inside WSL. WSL imports the Windows PATH by default, so npm and node can resolve to the Windows programs. Check:

which npm
which node

Paths that start with /mnt/c/ are Windows binaries. The quickest fix is to stop using npm for this and run the native installer:

npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

If you want to stay on npm, install Node inside WSL with nvm and make sure the loader is in ~/.bashrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

For a platform mismatch during npm install, the docs say to run npm config set os linux first and then npm install -g @anthropic-ai/claude-code --force, without sudo.

Don’t “fix” this by setting appendWindowsPath = false in /etc/wsl.conf. The docs warn against it, because it also breaks calling Windows programs such as explorer.exe and code from WSL.

Search finds fewer files than expected

The project is on the Windows drive. See Keep your projects off /mnt/c. claude doctor reports Search as OK in this case, so the only signs are slow turns and missing matches.

If search fails everywhere, including in your Linux home, the bundled ripgrep may not run on your system. Install the system package and tell Claude Code to use it:

sudo apt install ripgrep

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

The JSON goes into ~/.claude/settings.json. Afterwards, the Search line in claude doctor shows the path of the system ripgrep instead of OK (bundled).

Sandboxing requires WSL2 and a Dependencies-only sandbox panel

Sandboxing requires WSL2 means the distribution runs on WSL1. Check with wsl -l -v and convert it as shown above.

If /sandbox opens with only a Dependencies tab, the sandbox can’t start yet. Install what the tab lists, usually this, and restart Claude Code:

sudo apt-get install bubblewrap socat

If the tab reports Ubuntu’s AppArmor restriction on user namespaces, add a profile for bubblewrap:

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
sudo systemctl reload apparmor

A Dependencies tab next to the other tabs is fine. It lists an optional item, such as the seccomp filter, and the sandbox starts without it.

Sandboxed commands and Windows programs

On WSL2, starting cmd.exe, powershell.exe or anything under /mnt/c/ goes through a Unix socket to the Windows host. With the optional seccomp filter installed, the sandbox blocks Unix sockets, and those launches fail. If your workflow needs them, this setting opens every Unix socket to sandboxed commands:

{
  "sandbox": {
    "network": {
      "allowAllUnixSockets": true
    }
  }
}

That’s a real trade-off, because it also opens sockets such as the Docker socket. The narrower choice is to keep Windows programs out of the tasks you run sandboxed.

Killed during install (exit code 137)

The Linux out-of-memory killer stopped the installer. The script prints Installation was killed before it could finish (exit code 137) and notes that installing needs roughly 512 MB of free memory.

On WSL2 the usual cause is a tight memory limit in .wslconfig, or a lot of other programs running inside the distribution. Close what you don’t need, or raise the limit in C:\Users\YourUsername\.wslconfig:

[wsl2]
memory=8GB

Run wsl --shutdown in PowerShell, reopen the distribution and install again. Claude Code itself wants at least 4 GB of RAM.

JetBrains: No available IDEs detected

The JetBrains IDE runs on Windows, Claude Code runs in WSL2, and WSL2’s NAT networking or Windows Firewall blocks the connection between them. The docs list two fixes.

Firewall rule (keeps your networking mode). Inside WSL, find your address:

hostname -I

Take the first two segments and add .0.0/16. For 172.21.123.45 that’s 172.21.0.0/16. Then open PowerShell as Administrator and create the rule with your subnet:

New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

Restart the IDE and Claude Code.

Mirrored networking (Windows 11 22H2 or later). Add this to .wslconfig in your Windows user folder and run wsl --shutdown:

[wsl2]
networkingMode=mirrored

My WSL2 network settings guide covers what mirrored mode changes for the rest of your setup.

If clicking the Claude icon in the IDE says the command isn’t found, set the plugin’s Claude command (Settings, Tools, Claude Code) to this, with your distribution name:

wsl -d Ubuntu -- bash -lic "claude"

Image paste does nothing

On WSL, both Ctrl+V and Alt+V paste an image from the clipboard. Windows Terminal often takes Ctrl+V for itself, so use Alt+V. A working paste inserts an [Image #N] chip at the cursor.

Shift+Enter for a new line works out of the box in Windows Terminal.

Use it with VS Code

Open the project from the WSL terminal so VS Code connects to the Linux side:

cd ~/projects/my-app
code .

Then run claude in the integrated terminal. Two things to keep straight:

• In a window connected to WSL, Claude Code’s settings are the ones in the Linux home (~/.claude/settings.json), not the ones under your Windows user folder.
• If text looks garbled in the integrated terminal, run /terminal-setup inside Claude Code. It turns off the terminal’s GPU renderer, which is the usual cause.

If you haven’t set up the editor yet, see Install VS Code on WSL2.

Update and uninstall

The native install updates itself in the background, and the new version takes effect the next time you start Claude Code. To update right now:

claude update

To follow the slower release channel, which is about a week behind and skips releases with major regressions, set this in ~/.claude/settings.json:

{
  "autoUpdatesChannel": "stable"
}

To remove Claude Code from WSL:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Your settings and session history stay in ~/.claude and ~/.claude.json until you delete those too.

FAQ

Do I need Node.js to run Claude Code on WSL2?

No. The native installer downloads a standalone binary that doesn’t use Node.js. Only the npm install method needs Node, version 22 or later, and even then the package downloads the same native binary.

Is Claude Code faster on WSL2 or on native Windows?

It depends on where the files are. For a project in your Linux home, WSL2 is the fast path. For a project on the Windows drive, native Windows is faster, because WSL2 reads /mnt/c through a slower cross-system layer.

Can I run Claude Code on WSL1?

Yes, with limits. The sandbox isn’t supported on WSL1, and current versions can fail with Exec format error until you add the workaround from the error index. Converting the distribution to WSL2 is the better fix.

Where does Claude Code store its settings in WSL?

In your Linux home: ~/.claude/ for settings and session history, and ~/.claude.json for state. A native Windows install keeps its own copies under your Windows user folder, so the two don’t share settings.

Which Claude plan do I need?

A paid one: Pro, Max, Ultra, Team or Enterprise, or a Claude Console account. The free claude.ai plan doesn’t include Claude Code.

Do I need Git for Windows?

Not for WSL. Git for Windows is only relevant for the native Windows install, where it provides the Bash tool. Inside WSL, Claude Code uses the distribution’s own shell and its own git.

Related guides

• WSL2 Performance Optimization: Speed Up Your Linux Experience
• WSL2 Network Settings and Configuration Guide
• Install WSL2 on Windows: The Complete Step-by-Step Tutorial
• How to Install Docker in WSL2 Without Docker Desktop
• Claude Code settings.local.json Secrets: Audit Your Repos, Rotate, and Stop the Leak
• Claude Code Plan Mode vs One-Shot: Same App, 5 Ways
• How to Run Claude Code on a VPS, if you’d rather keep the agent off your Windows machine
• Claude Custom Instructions: The 10-Line File That Kills Walls of Text

Your turn

Hit an error on WSL2 that isn’t in the index? Send it to me on X @StefanRows with the exact message, and I’ll add it with the fix.