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; runwinget upgrade Anthropic.ClaudeCodenow 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 Windows | WSL 2 | |
|---|---|---|
| Where your repo lives | Windows file system, for example C:\Users\you\Project | Linux file system, for example /home/you/Project |
| File speed | Fast for Windows tools | Fast inside Linux; working under /mnt/c/... is slower |
| Toolchains | Windows-native projects and tools | Linux toolchains |
| Claude Code sandboxing | Not supported | Supported (not on WSL 1) |
| Codex sandbox | Windows sandbox (mxc, elevated or unelevated) | Linux sandbox; WSL 1 isn’t supported since Codex 0.115 |
| Install | PowerShell or CMD installers above | curl -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, wherecurlis an alias forInvoke-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 -gpackage 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 loginorcodex 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?
Is Codex CLI on Windows still experimental?
Should my repo be on C: or in the WSL file system?
/mnt/c are slower. Working natively, keep it on the Windows file system.Which Node.js version do I need?
node --version.Do I need a paid plan?
Sources
- Advanced setup, Anthropic (checked 2026-11-19)
- Troubleshoot installation and login, Anthropic (checked 2026-11-19)
- CLI reference, Anthropic (checked 2026-11-19)
- Windows sandbox, OpenAI (checked 2026-11-19)
- WSL, OpenAI (checked 2026-11-19)
- Authentication, OpenAI (checked 2026-11-19)
- openai/codex README, OpenAI (checked 2026-11-19)
- Gemini CLI installation, Google (checked 2026-11-19)
- Install WSL, Microsoft (checked 2026-11-19)
- Working across file systems, Microsoft (checked 2026-11-19)
- about_Execution_Policies, Microsoft (checked 2026-11-19)
- Folders, npm Docs (checked 2026-11-19)