Troubleshoot installation and login changedtroubleshoot-install
Nearest release: v2.1.314, published 4 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 29 Oct 2026 20:03 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 29 Oct 2026 20:07 UTC.
Upstream edited
Recorded here
Lines+35added
Lines−3removed
From line
991
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits27to this page, all time
#### Fix an npm 12 install
The whole hunk
from line 991, old and new numbered
/
from line 991
991991
992992### npm install errors in WSL
993993
994These issues apply if you installed Claude Code with `npm install -g` inside WSL. If you used the [native installer](https://code.claude.com/docs/en/setup.md), skip this section.
994These issues apply if you installed Claude Code with `npm install -g` inside WSL. If you used the [native installer](https://code.claude.com/docs/en/setup.md), skip this section. On npm 12, install as [Fix an npm 12 install](#fix-an-npm-12-install) describes.
995995
996996**OS or platform detection issues.** If npm reports a platform mismatch during install, WSL is likely picking up the Windows `npm`. Run `npm config set os linux` first, then install with `npm install -g @anthropic-ai/claude-code --force`. Do not use `sudo`.
997997
from line 1033
10331033
10341034### Native binary not found after npm install
10351035
1036The `@anthropic-ai/claude-code` npm package downloads the native binary as a per-platform optional dependency, such as `@anthropic-ai/claude-code-darwin-arm64`. npm then runs the package's postinstall script, which copies that binary into place as the `claude` command; until it runs, `claude` is a placeholder script. If either the download or the postinstall step is skipped, the placeholder stays in place, and running `claude` on macOS and Linux prints:
1036The `@anthropic-ai/claude-code` npm package downloads the native binary as a per-platform optional dependency, such as `@anthropic-ai/claude-code-darwin-arm64`. `claude` is a placeholder script until the `@anthropic-ai/claude-code` package's postinstall step runs and replaces the placeholder with that binary. If either the download or the postinstall step is skipped, the placeholder stays in place, and running `claude` on macOS and Linux prints:
10371037
10381038```text theme={null}
10391039Error: claude native binary not installed.
from line 1052
10521052
10531053Check the following causes:
10541054
1055* **npm 12 skips the postinstall step by default.** When you install or update Claude Code with npm 12, npm still finishes the install without running the step. See [Fix an npm 12 install](#fix-an-npm-12-install).
10551056* **Optional dependencies are disabled.** Remove `--omit=optional` from your npm install command, `--no-optional` from pnpm, or `--ignore-optional` from yarn, and check that `.npmrc` does not set `optional=false`. Then reinstall. The native binary is delivered only as an optional dependency, so there is no JavaScript fallback if it is skipped, and running `install.cjs` again can't place a binary that was never downloaded.
10561057* **Install scripts are disabled.** `--ignore-scripts` and some pnpm configurations skip the postinstall step but still download the platform package. Run `node node_modules/@anthropic-ai/claude-code/install.cjs` as the message suggests, or reinstall without the flag. If postinstall can't run in your environment at all, `node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs` finds the downloaded package and launches it, at the cost of an extra Node process on each start. If the wrapper prints `Could not find native binary package` instead, the platform package was never downloaded, so fix the optional-dependencies cause above first.
10571058* **Unsupported platform.** Prebuilt binaries are published for `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`, and `win32-arm64`. Claude Code does not ship a binary for other platforms; see the [system requirements](https://code.claude.com/docs/en/setup.md#system-requirements). On FreeBSD, the installer reports the platform as unsupported. Before v2.1.205, it treated FreeBSD as Linux and downloaded a binary that couldn't run.
10581059* **Corporate npm mirror is missing the platform packages.** Ensure your registry mirrors all eight `@anthropic-ai/claude-code-*` platform packages in addition to the meta package.
10591060
1061#### Fix an npm 12 install
1062
1063If `claude` prints `Error: claude native binary not installed.` after an npm install or update, or on Windows the shell can't run it, run `npm --version`. A version starting with `12` means that, unless your npm config allows it, npm skipped Claude Code's postinstall step, which puts the binary in place. For any other version, check the [other causes](#native-binary-not-found-after-npm-install).
1064
1065To fix an npm 12 install, switch to the native installer or allow the step:
1066
1067* **Switch to the native installer**: [install with the native installer](https://code.claude.com/docs/en/setup.md#install-claude-code), then [uninstall the npm package](https://code.claude.com/docs/en/setup.md#uninstall-with-npm). Updates then don't use npm, so the error doesn't come back.
1068* **Stay on npm**: for a global npm install, add Claude Code to `allow-scripts` in your user npm config. npm then runs Claude Code's install scripts on every later install and update, and in project installs whose `package.json` sets no `allowScripts`.
1069
1070 Use the native installer for a local install in `~/.claude/local`. Also use it if your `package.json` scripts call `npm install` and you run them with pnpm 9, pnpm 10, Yarn 1 or another tool that passes them this setting. On npm 12.1 and later, those installs can fail with `EALLOWSCRIPTS` once the setting is saved.
1071
1072 1. If `npm --version` printed 12.0.x, update npm to 12.1 or later, for example with `npm install -g npm@latest`. On 12.0.x, project installs that an `npx` tool or an `npm run` script starts can fail with `EALLOWSCRIPTS` once the setting is saved.
1073
1074 2. Run `npm config get allow-scripts` and note any packages it lists, because the next command replaces the whole value. Save the setting with those packages inside the quotes, as in `"allow-scripts=@anthropic-ai/claude-code,<package>"`:
1075
1076 ```bash theme={null}
1077 npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user
1078 ```
1079
1080 3. Reinstall:
1081
1082 ```bash theme={null}
1083 npm install -g @anthropic-ai/claude-code
1084 ```
1085
1086 If this or step 1 fails with `EACCES`, switch to the native installer instead of rerunning it with `sudo`. Claude Code runs npm without `sudo` when it updates itself, so automatic updates would fail the same way.
1087
1088 4. If `claude --version` doesn't print a version number, check the [other causes](#native-binary-not-found-after-npm-install).
1089
1090 To undo, set the list again without `@anthropic-ai/claude-code`, or remove the whole list with `npm config delete allow-scripts --location=user`. On npm 12, the error then returns after your next update.
1091
10601092### npm `ENOTEMPTY` error during update or reinstall
10611093
10621094When you run `npm install -g @anthropic-ai/claude-code` over an existing installation, npm can fail while moving the old package directory aside:
from line 1122
10901122Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"
10911123```
10921124
1093Then reinstall:
1125Then reinstall. On npm 12, follow [Fix an npm 12 install](#fix-an-npm-12-install). Otherwise, run:
10941126
10951127```bash theme={null}
10961128npm install -g @anthropic-ai/claude-code
No line in this hunk matches that.