Install Claude Code on Windows: npm, WSL2 and error fixes

On Windows, Claude Code installs with one npm command, npm install -g @anthropic-ai/claude-code, and then you run claude. The whole setup takes about 15 minutes, and only one requirement really matters: Node.js 18 or newer. That is the short version. The rest of this guide covers where people usually stumble: whether to run it natively or inside WSL2, how to sign in without an Anthropic account, and how to fix the PATH and execution-policy errors that turn 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 now runs natively on Windows, so WSL is not strictly required. Many people still find WSL2 noticeably smoother, so we cover both.

What do you need before installing Claude Code on Windows?

Three things:

• Windows 10 or 11. Older versions (7 and 8) are not supported, and the CLI usually will not start on them.
• Node.js 18 or newer (LTS). Claude Code ships as an npm package, so Node and npm have to be there.
• A way to authenticate: an Anthropic account or subscription, an Anthropic API key, or a codexkey key. More on that below.

Why Node 18 in particular? The CLI relies on runtime features that older Node builds lack. A current LTS clears a whole class of "crashes on launch" complaints.

Installing Node.js on Windows

Download the LTS installer from nodejs.org, run it and keep the defaults: it adds Node and npm to your PATH on its own. Open a new PowerShell window and check:

node --version
npm --version

node --version should print v18.x.x or higher (v20 and v22 LTS both work). If node is not recognized, close every terminal window and open a new one: PATH changes do not reach shells that were already open.

Used to version managers? On native Windows people mostly pick nvm-windows; inside WSL2, plain nvm.

Native PowerShell or WSL2: which should you pick?

Both work. Here is an honest comparison.

In short: if you already live in PowerShell and the project targets Windows, install natively. If your toolchain expects a Unix environment, as most Node, Python and Go work does, WSL2 will save you some nerves. WSL2 comes with one important rule: keep your code in the Linux filesystem (/home/you/projects), not under /mnt/c/.... Access across the filesystem boundary is slow and confuses file watchers.

Setting up WSL2 (if you go that way)

In PowerShell as administrator:

wsl --install

The command enables WSL, installs WSL2 and pulls Ubuntu by default. Reboot when asked, launch "Ubuntu" from the Start menu and set a Linux username and password. Inside Ubuntu, install Node through nvm or your package manager and continue with the npm install: the command is the same. Run node --version inside Ubuntu itself. Node on Windows and Node in WSL2 are two separate installations, and the LTS has to be in the one where you run claude.

How do you install Claude Code with npm?

The command is identical in native PowerShell and in WSL2:

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

The -g flag installs the package globally, so claude is available from any folder. When it finishes, check:

claude --version

You should see a version string. If the install fails with a permissions error, do not reach for sudo on npm's global directory: it creates more problems than it solves. The clean fix is in the errors section below.

Skip npm install -g on Windows itself? Some people run everything inside WSL2 only and never touch native npm. That is fine. Pick one environment and stay in it, or you will end up with two claude binaries.

First run and authentication

Go to a 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. There are three options.

Option A: Anthropic account or subscription

If you have a Claude Pro or Max subscription, or a Console account, choose the login flow. Claude Code opens a browser, you sign in, and the token is stored. It is simple, provided you can create and keep an Anthropic account. Many developers outside the US cannot, because signup checks your IP, phone number and card country all at once.

Option B: Anthropic API key

Have an sk-ant-… key from the Anthropic Console? Set it as an environment variable and Claude Code uses it directly. Billing goes through your Anthropic account.

Option C: codexkey key (no Anthropic account, no VPN)

This route is for people without an Anthropic account or working from Russia. codexkey is a gateway to Claude that speaks the same Messages API protocol. You get a key in the sk_cdx_… format, point Claude Code at the codexkey address, and everything else works as usual: MCP servers, hooks, all of it. No VPN and no Anthropic signup. Payment is per token from $0.33 per 1M tokens, and SBP (the Russian Faster Payments System), Russian cards, MTS (a Russian mobile operator) and crypto are accepted.

Pointing Claude Code at codexkey

Claude Code reads two environment variables: the base URL and credentials. Put the codexkey address in ANTHROPIC_BASE_URL and pass the key through ANTHROPIC_API_KEY (Claude Code also accepts ANTHROPIC_AUTH_TOKEN for the same purpose). Before you start, check the exact variable names against the Claude Code guide.

Get a codexkey key first

1. Register on the sign-up page: only an email is needed.
2. Top up the balance with SBP, a Russian or international card, MTS or crypto. There is no minimum.
3. Dashboard → API Keys → create a key. Copy the sk_cdx_… value.

PowerShell: try it for one session

A quick test in the current window only:

$env:ANTHROPIC_BASE_URL = "https://api.codexkey.online"
$env:ANTHROPIC_API_KEY  = "sk_cdx_YOUR_KEY"
claude

The values vanish when the window closes. That is fine for a test and wrong 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.codexkey.online"
setx ANTHROPIC_API_KEY  "sk_cdx_YOUR_KEY"

setx saves the variables but does not update the current window. Close PowerShell, open a new window and run claude.

WSL2 / Ubuntu

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

export ANTHROPIC_BASE_URL="https://api.codexkey.online"
export ANTHROPIC_API_KEY="sk_cdx_YOUR_KEY"

Reload the profile with source ~/.bashrc. Run claude in any repo and the agent goes through codexkey.

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 inside a repo and ask something simple: "list the files in this project." A correct answer means auth and the network are fine.
3. Ask for a tiny change, for example "add a comment at the top of README.md", and confirm the file changed.

If step 2 ends with an auth error, your key or base URL did not take. Move on to the errors section.

Configuring MCP servers on Windows

MCP (Model Context Protocol) servers extend Claude Code with tools: filesystem access, web requests, database connectors and more. They work the same with an Anthropic account and with codexkey, because the gateway is transparent to MCP.

You can add a server through the CLI:

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

On native Windows, watch the path format: backslashes and spaces in folder names need care. Inside WSL2, use Linux paths (/home/you/projects). claude mcp list prints the configured servers. More in the MCP servers guide.

Common Windows errors and how to fix them

claude is not recognized / node is not recognized. The install directory is not on PATH, or the terminal was opened before the install. Open a new PowerShell window first. Still failing? Look at $env:PATH (PowerShell) and make sure npm's global bin folder is in it; npm config get prefix tells you where it is.

npm ERR! EACCES / permission denied on global install. Do not run sudo on the global directory. On native Windows this is rare; if it happens, reinstall Node with the official installer (it sets permissions correctly). In WSL2, point npm's global prefix at your home directory:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Then reinstall: npm install -g @anthropic-ai/claude-code.

running scripts is disabled on this system (execution policy). PowerShell blocks scripts by default. Allow signed local scripts for your user:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

The setting applies to your account only and counts as standard and safe.

401 Unauthorized / invalid_api_key. The key has a stray space, or an old value is still in the environment. Create a new key in the codexkey dashboard, set the variable again and open a new terminal.

getaddrinfo ENOTFOUND api.anthropic.com. ANTHROPIC_BASE_URL did not apply. Run echo $env:ANTHROPIC_BASE_URL (PowerShell) or echo $ANTHROPIC_BASE_URL (WSL): it must print https://api.codexkey.online. Empty? You set it with setx but did not open a new window.

429 rate_limit_exceeded. Read the error text and the provider's rules. If there is a Retry-After, respect it and lower the request rate in your client. The dashboard key API does not let you set a per-key daily cap.

Updating and uninstalling Claude Code

To update to the latest release:

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

Then check claude --version. To remove it completely:

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

That deletes the binary, while your environment variables stay set: clear them in PowerShell with setx ANTHROPIC_API_KEY "" (then open a new window) or delete the export lines from ~/.bashrc in WSL.

Where to go next

• Just starting out? Take a look at the Claude Code setup guide.
• Working from Russia or without an Anthropic account? The Russia setup walkthrough goes deeper on payment and access.
• Choosing a tool? Read Claude Code vs Cursor.
• Connecting the gateway? The Claude Code guide holds the canonical config, and the quickstart gets you a key in a couple of minutes.

Ready to connect? Get a key and follow the Claude Code guide: the agent will be editing your repo before your coffee goes cold.

FAQ

Do I need WSL to run Claude Code on Windows? No. It runs natively in PowerShell or Windows Terminal. WSL2 is optional: it suits Unix toolchains better, but many people work without it just fine.

Does Claude Code work without an Anthropic account? Yes, through codexkey. The gateway issues its own sk_cdx_… keys, so no Anthropic signup is needed. No VPN is required either, and it is reachable from Russia.

Which Node.js version should I install? The current LTS: 18 at minimum, 20 or 22 recommended. On older versions Claude Code may crash on launch.

How do I download Claude Code: is there an .exe installer? The supported install path on Windows is npm: npm install -g @anthropic-ai/claude-code. You do not need to download a separate installer, npm does it all.

Will MCP servers and hooks work on Windows? Yes. They work natively and inside WSL2, and they behave the same when you sign in through Anthropic or through codexkey. On native Windows, mind the path format.

Questions? Reach the team on Telegram at https://t.me/codex_key or through the contact page.