Omniscio

OmniscioGuidesClaude Code in WSL

Claude Code in WSL: setup from a clean Windows

Claude Code runs inside WSL 2 as a normal Linux program, and the setup is three steps: turn WSL on, open the Linux distribution, and install Claude Code in its terminal.

Each step is a short set of commands, and the page says which window to type them in. Where a step needs a choice, it tells you the one to pick.

Last checked against Anthropic's and Microsoft's documentation on November 16, 2026. By the Omniscio team. Updated .

Do you need WSL at all?

No. Anthropic supports Claude Code natively on Windows 10 1809 or later, and its setup page lists native Windows and WSL as two routes with different costs rather than one right answer.

WSL gives you two things native Windows does not. You get a real Linux environment, which is the shell most Claude Code guides assume. You also get sandboxing: Anthropic's setup table lists it as supported on WSL 2 and not supported on native Windows.

The cost is a boundary in the middle of your work. Two filesystems, two sets of tools, and the slower file access Microsoft documents when a project sits on the other side of that boundary.

Pick WSL when the project itself is Linux-shaped: containers, shell scripts, a build pipeline, or anything that expects /usr paths. Pick native Windows when the project is Windows-shaped. The Windows guide sets the two side by side.

Source: the Set up on Windows table and the sandboxing row on Anthropic's setup page, read November 16, 2026.

Turn on WSL 2

Microsoft's prerequisite is Windows 10 version 2004 or later (build 19041 or higher) or Windows 11. On anything older the single command below is not available, and Microsoft's manual install steps apply instead.

Open PowerShell in administrator mode: search for it, right-click it and choose Run as administrator. Then run one command and restart the machine:

wsl --install

That command enables the Windows features WSL needs and installs Ubuntu as the default distribution. You can install a different distribution instead with wsl --install -d <name>.

If wsl --install prints the WSL help text instead of installing, WSL is partly present already. List what is available and install one by name:

wsl --list --online
wsl --install -d Ubuntu

An install that hangs at 0.0% has a documented second route: wsl --install --web-download -d Ubuntu, which fetches the distribution over the web instead of through the store.

Source: Microsoft's Install WSL page, read November 16, 2026.

Check you are on WSL 2

Which version you are on decides whether sandboxing works and whether the binary runs at all, so check it once rather than assume. These are PowerShell commands, run before you install anything inside the distribution.

PS> wsl -l -v
  NAME              STATE           VERSION
* Ubuntu            Running         2

The lines above show the shape of the output. Your distribution name is whatever you installed, and the * marks the default one.

A 1 in the VERSION column is WSL 1. Microsoft's comparison says WSL 1 has no full Linux kernel and no full system-call compatibility, and Anthropic's WSL 1 failure is the binary's program headers changing in a way that loader cannot handle.

To convert a distribution, Anthropic's own fix for its WSL 1 regression is this command, run from PowerShell with the distribution's name from the list above:

wsl --set-version Ubuntu 2

Run the conversion before you set the project up rather than after.

Sources: Microsoft's Comparing WSL versions page and the Exec format error entry in Anthropic's install troubleshooting page, read November 16, 2026.

Install Claude Code inside WSL

Open the distribution from the Start menu. The first launch asks you to create a Linux username and password — the password does not appear as you type — and Microsoft notes that first launch takes a while while the files decompress.

Everything from here happens inside WSL, in that window or a new one you open for it. Anthropic's words are that you install and launch claude inside the WSL terminal, not from PowerShell or CMD. Run the Linux installer, and paste it with Ctrl, Shift and V:

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

Then open a new WSL terminal and check it. Type the command without the $, which stands for the prompt:

$ claude --version
2.1.325 (Claude Code)

You do not need Git for Windows for a WSL setup.

If the shell says command not found: claude, the installer put it in ~/.local/bin and did not add that to PATH. The Linux guide has the fix, and the command not found guide covers the rest.

Sources: the Install in WSL and Set up on Windows sections of Anthropic's setup page, read November 16, 2026.

Where your projects belong

Put the project on the Linux filesystem, under /home/yourname: mkdir -p ~/projects/app creates one and cd ~/projects/app takes you into it. Microsoft's guidance is direct: store your files in the filesystem of the operating system you work in, and for the fastest performance keep project files on the WSL drive.

A Windows folder reached from WSL looks like /mnt/c/Users/yourname/Project. That works, and Microsoft says your performance speed improves when the files sit on the WSL drive instead.

Good   /home/yourname/projects/app
Slower /mnt/c/Users/yourname/projects/app

You can open the Linux folder in Windows Explorer by running explorer.exe . inside WSL. That gives you Windows tooling on Linux files without moving the files.

Git matters here too: Windows writes a line ending as two characters and Linux writes one, so keeping the project on one side keeps the whole repository consistent.

Sources: Microsoft's Working across Windows and Linux file systems page for where to store project files, and the Pro Git chapter on git configuration for the two line-ending characters, both read November 16, 2026.

Sign in when no browser opens

To sign in, type claude and press Enter. Under WSL 2 that flow can end with no browser opening, or with a connection error for a localhost address. Anthropic documents a way to finish it without fixing either problem.

At the login prompt, press c to copy the URL, or select it in the window and copy it, then open it in a browser on Windows and sign in. The browser displays a code instead of returning to localhost. Paste that code at the prompt that begins Paste code here.

If pasting into the prompt does nothing, use the command form, which reads the code from standard input:

claude auth login

To let it open a Windows browser next time, point BROWSER at one, adjusting the path to yours. This line lasts for the current terminal only; add it to ~/.bashrc to keep it.

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

That path crosses the filesystem boundary on purpose, to reach a browser that is installed on Windows.

Source: the OAuth login fails in WSL2 section of Anthropic's install troubleshooting page, read November 16, 2026.

The errors only WSL prints

Four failures are specific to this setup, and each has one documented cause. Three of them apply only if you installed Claude Code with npm; the installer on this page does not hit them.

cannot execute binary file: Exec format error means you are on WSL 1. Anthropic tracks it as a known native-binary regression in issue #38788. Converting to WSL 2 is the clean fix; if you must stay on WSL 1, Anthropic gives a shell function that runs the binary through the dynamic linker.

exec: node: not found after an npm install means WSL is calling the Windows Node.js. Run which npm and which node: a path starting /mnt/c/ is a Windows binary, while a Linux one starts /usr/. Install Node inside Linux to fix it, with your distribution's package manager or with nvm.

An nvm version that will not stick has the same root. WSL imports the Windows PATH by default, so a Windows nvm can take priority. Loading nvm in your shell configuration restores the Linux one, and Anthropic's install troubleshooting page gives the lines.

A platform mismatch during an npm install is fixed by running npm config set os linux, then npm install -g @anthropic-ai/claude-code@latest --force. Anthropic says not to use sudo for any of it.

One warning applies to all four. Do not set appendWindowsPath to false to solve a PATH clash. Anthropic says that breaks calling Windows programs from WSL, which you will want again before long.

Source: the Exec format error on WSL1 and npm install errors in WSL sections of Anthropic's install troubleshooting page, and issue #38788, read November 16, 2026.

Sandboxing, and what it needs

Sandboxing is the clearest reason to choose WSL over native Windows, and it is version-specific. Anthropic's setup table lists it as supported on WSL 2, and not supported on native Windows or on WSL 1.

The feature itself sets an operating-system boundary around the shell commands Claude runs. Anthropic describes it as enforced by the operating system rather than by Claude Code, which is why the underlying platform decides whether it is available.

The sandbox guide covers what it does and does not contain, and how a session reports a blocked command.

What runs under WSL is the Linux program itself, with Linux paths. The commands on the Linux install guide are the ones you type here.

Sources: the Set up on Windows table and the sandbox section of Anthropic's setup page, and its sandboxing page, read November 16, 2026.

Running several sessions at once

One WSL distribution holds as many Claude Code sessions as you open terminals for, one per terminal. Omniscio, the desktop app we make for running many Claude Code sessions at once, puts them in one window on Windows instead.

It is free to use with up to 8 projects, and Pro is $20/month or $192/year; neither plan includes an AI allowance. It installs on Windows, macOS and Linux.

If you are deciding between the two Windows routes for that reason, Claude Code on Windows sets native Windows and WSL side by side. The multi-session guide covers the by-hand options.

The toolchain update page explains how it keeps Claude Code current, and the update guide covers doing it yourself.

Where these answers come from

The release checked here was 2.1.325, the version npm served and claude --version printed on November 16, 2026. Both vendors change these pages, and Microsoft's WSL commands in particular gain flags with Windows releases, so read them again before trusting an old copy.

Common questions

How do I install Claude Code in WSL?

Install WSL 2 with wsl --install in an administrator PowerShell, restart, then open the Linux distribution itself. Inside its terminal, run curl -fsSL https://claude.ai/install.sh | bash. Anthropic is explicit that you install and launch claude inside the WSL terminal, never from PowerShell or CMD.

Do I need WSL to run Claude Code on Windows?

No. Claude Code installs natively on Windows 10 1809 or later with a PowerShell installer. WSL is worth it for two reasons: a real Linux toolchain, and sandboxing, which Anthropic lists as supported on WSL 2 but not on native Windows or WSL 1.

Where should I keep my project files in WSL?

On the Linux filesystem, under /home/yourname, not on a mounted Windows drive. Microsoft recommends storing files in the same operating system you work in, and says performance improves when project files sit on the WSL drive rather than under /mnt/c.

Why does claude fail with Exec format error in WSL?

You are on WSL 1. Anthropic tracks a known native-binary regression there as issue #38788, because the binary's program headers changed in a way WSL 1's loader cannot handle. The clean fix is wsl --set-version with your distribution name to move it to WSL 2.

Why does the WSL sign-in not open a browser?

Under WSL 2 the sign-in link can fail with no browser opening, or with a connection error. Anthropic's workaround is to copy the login URL, sign in with a browser on Windows, and paste the code back into the terminal. Setting BROWSER to a Windows browser's path lets it open directly next time.

Should I turn off Windows PATH sharing in WSL?

No. Anthropic warns against setting appendWindowsPath to false, because it breaks the ability to call Windows programs from inside WSL. WSL imports the Windows PATH by default, and that import is what can let a Windows Node.js shadow the Linux one and break an npm-installed claude.

Many WSL sessions, one window

Omniscio runs many Claude Code sessions side by side on the Claude Code you just installed, on Windows, macOS and Linux. The features page lists what it does today.