Guide

Claude Code and Codex CLI on Windows: do you need WSL?

Both run natively on Windows today. Here is how to install each one, when WSL 2 is still the better choice, and how to fix the install errors people hit most.

How do I install Claude Code on Windows?

Anthropic lists Windows 10 1809+ and Windows Server 2019+ as supported, on x64 or ARM64 with 4 GB of RAM or more. You can use PowerShell or CMD. Pick one of the official methods:

  • PowerShell (recommended native installer): irm https://claude.ai/install.ps1 | iex
  • CMD: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  • WinGet: winget install Anthropic.ClaudeCode. WinGet installs don’t auto-update; run winget upgrade Anthropic.ClaudeCode now and then.
  • npm: npm install -g @anthropic-ai/claude-code@latest. This needs Node.js 22 or later and installs the same native binary.

The native installer puts claude.exe in %USERPROFILE%\.local\bin and updates itself in the background. When it finishes, open a new terminal and check it:

claude --version
claude doctor

claude doctor prints read-only diagnostics about the install and your settings. Then run claude in your project folder and sign in in the browser. Claude Code needs a Pro, Max, Ultra, Team, Enterprise or Console account; the free claude.ai plan doesn’t include it.

Do I need Git for Windows?

It’s optional but recommended. With Git for Windows installed, Claude Code uses Git Bash for its Bash tool; without it, Claude Code runs shell commands through its PowerShell tool. If Claude Code can’t find Git Bash, set the path in ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Point it at bash.exe, not the git-bash.exe launcher. Claude Code ignores the variable when the file has any other name. Run where.exe git to find your Git folder.

Does Codex CLI work on native Windows?

Yes. OpenAI’s Windows documentation says you can use Codex on Windows natively with the CLI, the IDE extension or the desktop app, running in PowerShell with a Windows sandbox instead of WSL or a virtual machine. The page we checked doesn’t call native Windows support experimental. Windows 11 is the recommended baseline; Windows 10 needs version 1809 or newer.

Install it from PowerShell with the standalone installer, or with npm:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
npm install -g @openai/codex

Sign in with codex login (browser sign-in with ChatGPT) and check the method with codex login status. You can use an OpenAI Platform API key instead with codex login --with-api-key; that is billed at standard API rates.

The Codex Windows sandbox

The sandbox enforces the file and network permissions of the active permission profile for the commands Codex runs. There are three implementations:

  • mxc: recommended where supported. It needs Windows 11 24H2 (build 26100.9278) or 25H2 (build 26200.9278) with capabilities Microsoft is still rolling out, and no administrator setup.
  • elevated: the fallback Codex prefers when no mode is set. Setup needs administrator approval; the sandboxed commands themselves don’t run as administrator.
  • unelevated: for when elevated setup isn’t possible. Network isolation is weaker.

You choose a fallback in Codex’s config.toml with [windows] sandbox = "elevated" (or "unelevated").

What about Gemini CLI?

Google’s installation guide recommends Windows 11 24H2 or later and Node.js 20.0.0 or later, and lists PowerShell as a supported shell. Install it with npm install -g @google/gemini-cli.

Native Windows or WSL 2: which should you pick?

Native WindowsWSL 2
Where your repo livesWindows file system, for example C:\Users\you\ProjectLinux file system, for example /home/you/Project
File speedFast for Windows toolsFast inside Linux; working under /mnt/c/... is slower
ToolchainsWindows-native projects and toolsLinux toolchains
Claude Code sandboxingNot supportedSupported (not on WSL 1)
Codex sandboxWindows sandbox (mxc, elevated or unelevated)Linux sandbox; WSL 1 isn’t supported since Codex 0.115
InstallPowerShell or CMD installers abovecurl -fsSL https://claude.ai/install.sh | bash and curl -fsSL https://chatgpt.com/codex/install.sh | sh inside the WSL shell

Microsoft’s rule of thumb: keep files in the WSL file system if you work from a Linux command line, and in the Windows file system if you work from PowerShell or CMD. Mixing the two is where most slowness comes from. To set up WSL, run wsl --install in an administrator PowerShell and restart; new distributions use WSL 2 by default. Check with wsl -l -v.

Inside WSL, install Claude Code and Codex in the WSL terminal, not from PowerShell. If which node or which npm shows a path under /mnt/c/, WSL is using your Windows Node.js; install Node inside the Linux distribution.

Common install errors and how to fix them

'claude' is not recognized after installing

The install folder isn’t on your PATH. Check that the file exists, then add the folder to your user PATH and open a new terminal (restart your editor too if you use its terminal):

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

A CLI installed with npm isn’t found

On Windows, npm links global commands directly into its global prefix folder, which defaults to %AppData%\npm. Run npm prefix -g to see yours, make sure that folder is on your PATH, then open a new terminal.

“running scripts is disabled on this system”

PowerShell’s execution policy is blocking the npm.ps1 or claude.ps1 launchers that npm creates. Either allow local scripts for your user only (no administrator needed), call npm.cmd instead, or use the native installer, which doesn’t install a .ps1 script:

Get-ExecutionPolicy -List
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Microsoft notes that execution policy isn’t a security boundary. A Group Policy setting overrides it, so on a managed PC ask IT.

The wrong install command for your shell

  • 'irm' is not recognized: you’re in CMD. Use the CMD command or open PowerShell.
  • The token '&&' is not a valid statement separator: you’re in PowerShell. Use the PowerShell command.
  • A parameter cannot be found that matches parameter name 'fsSL': you ran the macOS/Linux command in PowerShell, where curl is an alias for Invoke-WebRequest.

Node.js is too old

Run node --version. Claude Code’s npm package needs Node.js 22 or later (on older versions npm prints an EBADENGINE warning), and Gemini CLI needs 20 or later. The native Claude Code installer doesn’t use Node.js at all.

“Exec format error” in WSL

You’re on WSL 1. Convert the distribution with wsl --set-version <DistroName> 2.

Where Pyloxa fits

Pyloxa is a native Windows 10 and 11 desktop app that gets Claude Code and Codex CLI working on the same project. It runs directly on Windows, with no WSL and no Docker. It needs Git for Windows 2.30 or later, and Node.js 22 or later only if you want it to install the CLIs for you.

The free version’s setup guide covers the steps on this page:

  • Environment check: git (required) and Node.js (optional). If one is missing or too old, copy the winget command it shows or open the official download page, then choose Check again.
  • Install agents: one card per CLI. It shows you the exact command first, then runs the CLI’s official npm install -g package at the latest version Pyloxa has verified.
  • Sign-in and keys: shows whether each CLI is Ready. You sign in in a terminal with claude auth login or codex login, or paste an API key. Pyloxa never reads, copies or sends your tokens. Gemini CLI is experimental and needs your own paid Gemini API key.

Windows-specific items from the troubleshooting section: if a CLI works in your terminal but Pyloxa says it isn’t installed, restart Pyloxa; if a task fails with “Couldn’t start claude” (or codex), your antivirus may be blocking it, so allow Pyloxa’s install folder rather than turning protection off. The installer isn’t code-signed yet, so SmartScreen may warn on first run.

Everything above is in the free version. If you only ever use one agent in one terminal, you don’t need Pyloxa; it helps when you want a plan split across both agents, each task in its own git worktree, and your own test commands deciding what passes. See the workflow page.

FAQ

Do I need WSL to run Claude Code on Windows?
No. Claude Code runs natively from PowerShell or CMD on Windows 10 1809+ and Windows Server 2019+. Use WSL 2 only if you want Claude Code’s sandboxing or Linux toolchains.
Is Codex CLI on Windows still experimental?
OpenAI’s current Windows page, checked on 2026-11-19, describes native Windows with a Windows sandbox as the default and doesn’t label it experimental. It recommends WSL 2 when you need Linux-native tools or your work already lives in WSL.
Should my repo be on C: or in the WSL file system?
Match it to where you run the tools. Working from WSL, keep the repo under your Linux home; paths under /mnt/c are slower. Working natively, keep it on the Windows file system.
Which Node.js version do I need?
The native Claude Code installer doesn’t need Node.js. For npm installs, Claude Code needs Node.js 22 or later and Gemini CLI needs 20.0.0 or later. Check yours with node --version.
Do I need a paid plan?
For Claude Code, yes: a Pro, Max, Ultra, Team, Enterprise or Console account. Codex CLI signs in with ChatGPT or uses an OpenAI API key billed at API rates. Check each vendor’s plan page for what’s included.

Sources

  1. Advanced setup, Anthropic (checked 2026-11-19)
  2. Troubleshoot installation and login, Anthropic (checked 2026-11-19)
  3. CLI reference, Anthropic (checked 2026-11-19)
  4. Windows sandbox, OpenAI (checked 2026-11-19)
  5. WSL, OpenAI (checked 2026-11-19)
  6. Authentication, OpenAI (checked 2026-11-19)
  7. openai/codex README, OpenAI (checked 2026-11-19)
  8. Gemini CLI installation, Google (checked 2026-11-19)
  9. Install WSL, Microsoft (checked 2026-11-19)
  10. Working across file systems, Microsoft (checked 2026-11-19)
  11. about_Execution_Policies, Microsoft (checked 2026-11-19)
  12. Folders, npm Docs (checked 2026-11-19)

Want this handled for you?

Pyloxa is a free Windows app that runs the Claude Code and Codex CLIs you already use: it splits the work by your rules, runs your tests itself and offers a handoff when one runs out of quota.