Install Claude Code on Windows: Step-by-Step Guide (2026)

Claude Code installs on Windows with one PowerShell command: irm https://claude.ai/install.ps1 | iex, then you run claude. You need neither administrator rights nor Node.js. The whole setup, authentication included, takes about 15 minutes. That's the short version. The rest of this guide covers the parts that actually trip people up: whether to run it natively or inside WSL2, how to authenticate when an Anthropic account is out of reach, and how to fix the PATH and execution-policy errors that show up on a fresh Windows machine.

Claude Code is Anthropic's command-line coding agent. It reads your repo, edits files, runs tests, and opens pull requests from the terminal. It runs natively on Windows, so you don't strictly need WSL, but the WSL2 experience is noticeably smoother for many developers, and we'll cover both.

What do you need before installing Claude Code on Windows?

Three things:

• Windows 10 version 1809 or newer, Windows 11, or Windows Server 2019+. Windows 7 and 8 aren't supported. You also need 4 GB of RAM and an x64 or ARM64 processor.
• Access to Anthropic's servers. The script and the binary are downloaded from there, and your country has to be on Anthropic's supported list. If the install hits a 403, see the install section below.
• A way to authenticate: a paid Anthropic account, an Anthropic API key, or a Claudexia API key. More on that below.

Node.js is not needed for the native install. You only need it if you install through npm or run MCP servers through npx.

Native PowerShell or WSL2: which should you pick?

Both work. Here's the honest trade-off.

Short answer: if you already live in PowerShell and your project is Windows-native, install natively. If your toolchain expects a Unix environment (most Node, Python, and Go work does) or you need sandboxing, WSL2 will save you headaches. One important rule with WSL2: keep your code inside the Linux filesystem (/home/you/projects), not under /mnt/c/.... Cross-filesystem access is slow and confuses file watchers.

Setting up WSL2 (if you go that route)

In an admin PowerShell (this needs Windows 10 version 2004 or newer, or Windows 11):

wsl --install

This enables WSL and installs Ubuntu on WSL 2 by default. Reboot when prompted, launch "Ubuntu" from the Start menu and create your Linux username and password. Then run the Linux installer inside Ubuntu:

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

Install and launch claude inside the Ubuntu terminal, not from PowerShell or CMD. The install on Windows and the install inside Ubuntu live separately: the binary in ~/.local/bin inside Ubuntu and the one in %USERPROFILE%\.local\bin on Windows are two different copies.

How do you install Claude Code on Windows?

PowerShell

irm https://claude.ai/install.ps1 | iex

While the script downloads it prints nothing. When the prompt comes back, open a new terminal window and check:

claude --version

You should see a line like 2.1.211 (Claude Code). The binary lives at %USERPROFILE%\.local\bin\claude.exe, and the install then updates itself in the background. For a deeper check there is claude doctor: it changes nothing and prints install and settings diagnostics with suggested fixes.

CMD

In classic CMD (a prompt like C:\Users\you> without PS) the command is different:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

The commands for the two shells are not interchangeable. The error The token '&&' is not a valid statement separator means you are in PowerShell and pasted the CMD line. The error 'irm' is not recognized means the opposite.

WinGet

winget install Anthropic.ClaudeCode

WinGet does not update Claude Code on its own: run winget upgrade Anthropic.ClaudeCode from time to time.

npm, if you specifically want it

The @anthropic-ai/claude-code package installs the same native binary, and claude does not call Node.js while it runs. Since version 2.1.198 the package declares Node.js 22 or newer. On an older Node npm prints an EBADENGINE warning, but the install completes and claude still starts. Simplest is to take the current LTS.

Grab the LTS installer from nodejs.org, run it, and accept the defaults. It adds Node and npm to your PATH automatically. Open a new PowerShell window and check:

node --version
npm --version

node --version should print v22.x.x or higher. If node isn't recognized, close every terminal window and open a new one, because PATH changes don't apply to shells that were already open. Prefer a version manager? On native Windows, nvm-windows is the common choice, and inside WSL2 use the standard nvm. Then:

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

The -g flag installs it globally so the claude command is available everywhere. Don't use sudo: Claude Code updates itself without it, so an install that needs sudo cannot update automatically.

Installed Claude Code both natively and through npm, or both on Windows and in WSL? You end up with two claude binaries, and whichever comes first on PATH runs. On Windows, list every copy with where.exe claude: it searches the current folder and the Windows PATH, and it will not see a Linux copy inside WSL. Check WSL separately: type -a claude lists every copy on the distribution's PATH. Pick one install and stay with it.

If the install doesn't go through

The script is served from claude.ai and the binary comes from downloads.claude.ai. Check whether the server answers:

curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

You need curl.exe specifically: in PowerShell curl is an alias for Invoke-WebRequest, which rejects the -sI flags. A first line of HTTP/1.1 200 OK means the server is reachable. A 403 usually means a proxy or network filter, or that Claude Code is not available in your region. In the second case the response contains the text App unavailable in region. Behind a corporate proxy, set HTTPS_PROXY and HTTP_PROXY before running the installer. We have not tested the install from every country; Download Claude Code walks through the checks one by one.

First run and authentication

Move into any project folder and start the agent:

cd C:\Users\you\projects\my-app   # PowerShell
# or, in WSL2:
cd ~/projects/my-app
claude

On first launch Claude Code asks how you want to authenticate. You have three options.

Option A: Anthropic account

You need a paid Claude plan (Pro, Max, Ultra, Team or Enterprise) or a Console account: the free claude.ai plan does not include Claude Code. Pick the login flow, Claude Code opens a browser, you sign in, and it stores the token. Straightforward if you can create and keep an Anthropic account. Many developers outside the US can't: cards get declined, and phone or billing checks can block signup.

Option B: Anthropic API key

Have an sk-ant-… key from the Anthropic Console? Set it in the ANTHROPIC_API_KEY environment variable. On first launch Claude Code asks whether to use the key and, once you approve, skips the browser login. Billing runs through your Anthropic account.

Option C: Claudexia key (no Anthropic account)

This is the route for developers who have no Anthropic account or whose payment does not go through. Claudexia accepts requests on the same Messages API protocol. You get a key in the sk_cdx_… format, point Claude Code at the Claudexia base URL, and everything else works the same: MCP servers, hooks, the lot. You skip Anthropic signup, and no VPN is needed to reach the Claudexia API. Payment is per token, each model's price is on the models page, and you can pay with a local card, Visa or Mastercard, USDT, BTC or ETH, plus SBP and rubles where they apply.

One caveat. Claudexia sells API access, not Claude Pro or Max subscriptions. A gateway does not change Anthropic's rules about which countries can use Claude Code, and you will have to read those terms yourself.

Pointing Claude Code at Claudexia

Claude Code takes the API address and the credentials from environment variables. You need five: ANTHROPIC_BASE_URL (the address, with no /v1), ANTHROPIC_AUTH_TOKEN (your key), and three ANTHROPIC_DEFAULT_*_MODEL variables for the opus, sonnet and haiku aliases. Without the last three Claude Code asks for its own default models and fails with "There's an issue with the selected model". The canonical variable list and model names are in the Claude Code guide.

Get a Claudexia key first

1. Sign up at claudexia.tech. A login and password, or Google, GitHub or Telegram, is all you need.
2. Top up the balance with a local or international card, USDT, BTC or ETH, or SBP where it exists. The minimum top-up is $1.
3. Dashboard → API Keys → create a key. Copy the sk_cdx_… value.

PowerShell: try it for one session

For a quick test in the current window only:

$env:ANTHROPIC_BASE_URL = "https://api.claudexia.tech"
$env:ANTHROPIC_AUTH_TOKEN = "sk_cdx_YOUR_KEY"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-sonnet-5"
claude

These vanish when you close the window. Good for testing, not for daily use.

PowerShell: make it persistent

To keep the values across reboots, write them to your user environment:

setx ANTHROPIC_BASE_URL "https://api.claudexia.tech"
setx ANTHROPIC_AUTH_TOKEN "sk_cdx_YOUR_KEY"
setx ANTHROPIC_DEFAULT_OPUS_MODEL "claude-opus-5-5[1m]"
setx ANTHROPIC_DEFAULT_SONNET_MODEL "claude-sonnet-5[1m]"
setx ANTHROPIC_DEFAULT_HAIKU_MODEL "claude-sonnet-5"

setx persists the variables, but it does not update the current window. Close PowerShell and open a fresh one, then run claude. The [1m] suffix is understood only by Claude Code. claude-sonnet-5 and claude-opus-5-5 already have a native 1M window, so the suffix changes nothing for them: it is in the examples for the case where your Claude Code version does not know these IDs and assumes a 200K window (it warns about that at startup; then run claude update). The suffix is needed for models that Claude Code opens at 1M only through it: claude-opus-4-6[1m] and claude-sonnet-4-6[1m]. Do not add it to claude-haiku-4.5, whose window is 200K. You can also put the same variables in the env block of %USERPROFILE%\.claude\settings.json; there is an example in the Claude Code setup guide.

WSL2 / Ubuntu

Add the exports to ~/.bashrc (or ~/.zshrc):

export ANTHROPIC_BASE_URL="https://api.claudexia.tech"
export ANTHROPIC_AUTH_TOKEN="sk_cdx_YOUR_KEY"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-sonnet-5"

Then reload: source ~/.bashrc. Run claude from any repo and the agent talks to Claudexia.

How do you verify Claude Code is working?

Quick checks, in order:

1. claude --version prints a build number: the binary is installed and on PATH.
2. Run claude and type /status. The Anthropic base URL line should read https://api.claudexia.tech, and the Auth token line should name ANTHROPIC_AUTH_TOKEN. If the address line is missing, the variable never reached the session. Setting ANTHROPIC_BASE_URL alone is not enough: a saved claude.ai login stays the active credential.
3. Inside a repo, ask something simple: "list the files in this project." A correct answer means auth and the network path both work.
4. Ask it to make a tiny change, "add a comment at the top of README.md", and confirm it edits the file.

If step 3 fails with an auth error, your key or base URL didn't take. Jump to troubleshooting.

Configuring MCP servers on Windows

MCP (Model Context Protocol) servers extend Claude Code with extra tools: filesystem access, web fetch, database connectors, and more. They behave the same whether you authenticate through Anthropic or Claudexia; the gateway is transparent to MCP.

Add a server with the CLI:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem C:\Users\you\projects

npx ships with Node.js, so a server like this needs Node even if you installed Claude Code natively. On native Windows, watch the path format: backslashes and spaces in folder names need care. Inside WSL2, use Linux paths (/home/you/projects). List configured servers with claude mcp list. For a deeper walkthrough, see our MCP servers guide.

Common Windows errors and how to fix them

claude is not recognized. The install succeeded but %USERPROFILE%\.local\bin is not on PATH: the installer does not change PATH itself, it only prints a hint at the end of its output. Open a brand-new PowerShell window first. A terminal inside an editor takes its PATH from the editor, so quit and reopen the editor too. Still failing? Check that the binary exists:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

True means the file is there and the folder has to go into your user PATH:

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

Restart the terminal and run claude --version again. If claude opens the Claude Desktop app instead of Claude Code, update Desktop: older versions put their own Claude.exe in WindowsApps, and it comes earlier on PATH.

node or npm is not recognized. This only matters for the npm route and for MCP servers launched with npx. Install the Node.js LTS from nodejs.org and open a new terminal window.

running scripts is disabled on this system (execution policy). This shows up with an npm install: PowerShell blocks the .ps1 launcher scripts that npm creates for the npm and claude commands. The irm ... | iex installer is not affected. There are three ways out. Allow locally created scripts for your user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Or call npm.cmd and claude.cmd, which the policy does not cover. Or install Claude Code with the PowerShell installer instead of npm.

claude won't start after an npm install, or prints Error: claude native binary not installed. On Windows, PowerShell and CMD usually say they cannot run the file, and the message itself shows up on macOS, Linux and in WSL. The usual cause is npm 12: it skips the package's install step by default, so the binary never lands in place. Run npm --version: if it starts with 12, the simplest fix is to switch to the native installer and remove the npm package with npm uninstall -g @anthropic-ai/claude-code.

EACCES or permission denied on an npm install. Don't sudo the global directory. Anthropic's docs recommend switching to the native installer, which writes only into your own profile folders.

WSL: cannot execute binary file: Exec format error. You are on WSL 1. Convert the distribution to WSL 2 from PowerShell, using the name from wsl -l -v:

wsl --set-version <DistroName> 2

WSL: exec: node: not found when running claude after an npm install. WSL picked up the Windows copy of Node. which node prints a path starting with /mnt/c/. Install Linux Node through nvm or your distribution's package manager.

Claude Code does not support 32-bit Windows. You opened the Windows PowerShell (x86) Start menu entry. Open Windows PowerShell without (x86) and run the installer again.

401 Unauthorized / invalid_api_key. The key has a stray space, or an old value is still in the environment. Our guides put the key in ANTHROPIC_AUTH_TOKEN, which Claude Code sends as Authorization: Bearer. The gateway also accepts x-api-key, so an sk_cdx_… key in ANTHROPIC_API_KEY does not cause a 401 by itself. If both variables are set, Claude Code's docs say ANTHROPIC_AUTH_TOKEN wins, and in an interactive session ANTHROPIC_API_KEY also waits for a one-time approval, so keep just one. /status shows which credential is active. Create a fresh key in the Claudexia dashboard, re-set the variable, and open a new terminal.

Unable to connect to API or (ENOTFOUND). Claude Code could not reach the API address. Run echo $env:ANTHROPIC_BASE_URL (PowerShell) or echo $ANTHROPIC_BASE_URL (WSL): it must print https://api.claudexia.tech. If it's empty, Claude Code goes to api.anthropic.com: you set it with setx but didn't reopen the window. If the address is there and the error text says Connection refused, check whether a stale address of a local gateway that is no longer running is left in your profile or in settings.json.

429 Too Many Requests. A 429 has several causes. Too many requests (rate_limited) or too many concurrent requests on one key (org_queue_full): slow down and let the current ones finish. The service is busy (queue_full, queue_timeout): retry in a few seconds. The balance is almost empty (low_balance): requests are processed one at a time, so top up. Claude Code speaks the Anthropic format, which carries a status and an error type rather than the code, so on a 429 check your balance in the dashboard first. Respect Retry-After if present. The dashboard key API does not expose per-key daily caps.

Updating and uninstalling Claude Code

A native install updates itself: Claude Code checks for updates at startup and periodically, installs them in the background, and the new version takes effect on the next launch. To update right now:

claude update

claude doctor shows the result of the last auto-update attempt. A WinGet install does not update itself: run winget upgrade Anthropic.ClaudeCode. For npm use npm install -g @anthropic-ai/claude-code@latest rather than npm update -g, which respects the version range from the first install and can skip a new release.

To remove a native install:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

For the other routes, run winget uninstall Anthropic.ClaudeCode or npm uninstall -g @anthropic-ai/claude-code. In WSL remove the binary with rm -f ~/.local/bin/claude and rm -rf ~/.local/share/claude.

Your settings, allowed tools, MCP configuration and session history live in %USERPROFILE%\.claude and %USERPROFILE%\.claude.json. They stay after you remove the program, so delete them only if you are fine losing all of that. Your environment variables stay set as well. Clear them from the Windows user environment like this:

foreach ($n in 'ANTHROPIC_BASE_URL','ANTHROPIC_AUTH_TOKEN','ANTHROPIC_DEFAULT_OPUS_MODEL','ANTHROPIC_DEFAULT_SONNET_MODEL','ANTHROPIC_DEFAULT_HAIKU_MODEL') {
  [Environment]::SetEnvironmentVariable($n, $null, 'User')
}

Then open a new window. In WSL delete the export lines from ~/.bashrc.

Where to go next

• New to the tool? Start with our Claude Code setup guide.
• No Anthropic account, or its signup and payment fail where you live? The setup walkthrough for blocked regions goes deeper on payment and access.
• Install failing, or want the full list of install routes? Read Download Claude Code.
• Deciding between tools? Read Claude Code vs Cursor.
• Connecting the gateway? The Claude Code guide has the canonical config, and the quickstart gets you a key in minutes.

FAQ

Do I need WSL to run Claude Code on Windows? No. It runs natively in PowerShell, CMD or Windows Terminal. WSL2 is optional: it is smoother for Unix-style toolchains and needed if you want sandboxing, which native Windows does not support.

Does Claude Code work without an Anthropic account? Yes, through Claudexia. The gateway issues its own sk_cdx_… keys, so you skip Anthropic signup, and no VPN is needed to reach the Claudexia API. The Claude Code installer itself is downloaded from Anthropic's servers: if your network cannot reach them, see "If the install doesn't go through".

Which Node.js version should I install? None for the native install. The npm route needs Node.js 22 or newer, details in the npm section above.

How do I download Claude Code, and is there an .exe installer? Among the official Windows routes Anthropic names PowerShell, CMD and WinGet, and none of them is a double-click .exe. Don't download files from third-party sites. There is also a separate Claude app for Windows (claude.com/download) that lets you use Claude Code without the terminal, but it is a different program: see Download Claude Desktop and connect MCP.

Will MCP servers and hooks work on Windows? Yes. They work natively and inside WSL2, and they behave identically whether you authenticate via Anthropic or Claudexia. Mind the path format on native Windows.

Questions? Reach the team on Telegram or email support@claudexia.tech.