If Claude Code stops with this, the fix is the command the message itself names:
node node_modules/@anthropic-ai/claude-code/install.cjs
Error: claude native binary not installed.
Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).
Run the postinstall manually (adjust path for local vs global install):
node node_modules/@anthropic-ai/claude-code/install.cjs
Or reinstall without --ignore-scripts / --omit=optional.
The install did not fail silently — it half-succeeded. @anthropic-ai/claude-code is a small meta package. The actual executable ships as a separate per-platform optional dependency (@anthropic-ai/claude-code-darwin-arm64, @anthropic-ai/claude-code-linux-x64, and so on), and a postinstall script copies it into place. Until both of those happen, the claude on your PATH is a placeholder script that does nothing but print the text above.
If install.cjs fixes it, you are done. If it does not, read on — that tells you which of the two causes you have.
The two causes, and how to tell them apart
The message lists both possibilities because the CLI cannot tell which one it hit. You can:
# Global install: find where npm put the package
ls "$(npm root -g)/@anthropic-ai/"
# Local install: look in the project
ls node_modules/@anthropic-ai/
Read the output.
If you see a platform package — a directory such as claude-code-darwin-arm64 — next to claude-code, the binary was downloaded and only the copy step was skipped. That is the --ignore-scripts case, and running install.cjs places it:
node "$(npm root -g)/@anthropic-ai/claude-code/install.cjs"
claude --version
If claude-code is the only directory there, the platform package was never fetched at all. This is the --omit=optional case. install.cjs cannot help — there is no binary on disk for it to copy — and re-running it will keep failing. Skip to the reinstall below.
Fix: reinstall without the flags that break it
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code
claude --version
No --ignore-scripts, no --omit=optional, no --no-optional, no --ignore-optional. If you did not pass any of those yourself, something in your configuration is passing them for you:
# Show every npm setting that is not a default, including .npmrc files
npm config list
# Check the two that matter directly
npm config get ignore-scripts
npm config get omit
ignore-scripts=true or optional=false in a user, project or global .npmrc will reapply on every install and make the error come back the moment you update. Remove the line rather than working around it:
npm config delete ignore-scripts
pnpm and yarn
pnpm blocks postinstall scripts from unknown packages by default in recent versions, which reproduces the --ignore-scripts case exactly. Allow the package explicitly, then reinstall:
pnpm approve-builds
For yarn, drop --ignore-optional and confirm enableScripts has not been set to false in .yarnrc.yml.
When it is neither flag
Two environments produce this error with a perfectly normal install command.
An incomplete corporate npm mirror. Internal registries frequently mirror only direct dependencies and skip optional ones, so the meta package resolves and the platform package 404s. Confirm by asking the registry directly:
npm view @anthropic-ai/claude-code-linux-x64 version
Substitute your own platform. If that errors against your internal registry but works against --registry=https://registry.npmjs.org, the mirror is the problem and your registry administrator has to add all eight platform packages. This is the most common cause of the error appearing on every machine in an organisation at once.
An unsupported platform. Prebuilt binaries exist for darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 and win32-arm64 — nothing else. On an architecture outside that list there is no package to download, and the closely related unsupported platform: no compatible Claude Code binary found message is what you will usually see instead.
The permanent fix: stop installing through npm
Every cause on this page is a consequence of the npm packaging. The native installer has no Node dependency, no postinstall step and no optional dependencies:
# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
Remove the npm copy afterwards so the old placeholder cannot win a PATH lookup:
npm uninstall -g @anthropic-ai/claude-code
hash -r # clear your shell's cached command locations
type -a claude # confirm only one claude remains
That type -a check matters. If the npm placeholder is still earlier in your PATH than the native binary, you will keep seeing this error after a successful native install and it will look like the installer failed.
Verify
claude --version
claude doctor
claude doctor reports the install type, the resolved binary path and the authentication state in one pass. If it reports a native install and claude --version prints a version, the binary is in place.
When the error reaches you through a wrapper
IDE extensions, desktop apps, MCP servers and CI jobs that shell out to claude catch this failure and re-print it with their own prefix, most often as Failed to run Claude Code: Error: claude native binary not installed. The prefix is the wrapper's; the error and the fix are the ones on this page. Claude Code itself never prints Failed to run Claude Code:.
If the text after Error: is something else, work through Claude Code installation errors, which covers the other wrapper messages.
Related guides
- zsh: command not found: claude — the binary installed, but your shell cannot find it
- zsh: permission denied: claude — the binary is found but not executable
- Could not locate the Claude CLI on PATH — the CLI works in your terminal but not in your editor
- Install Claude Code CLI — a clean install from scratch