All articles
Claude CodeClaudeFixes

Claude Code “claude native binary not installed”: 2 Causes and Tested Fixes (2026)

"claude native binary not installed" means the npm install finished halfway: either postinstall was skipped or the platform package was never downloaded. Look inside node_modules/@anthropic-ai first, then run install.cjs or reinstall. Tested on npm 11; npm 12 notes come from the official docs.

Claude native binary not installed: an empty clay package box with a loose clay gear and a small clay terminal
Also available in中文Español

Short answer: Error: claude native binary not installed. means the npm install finished only halfway. The claude command on your PATH is still a small placeholder script, because either the platform package was never downloaded (--omit=optional, or optional=false in .npmrc) or the postinstall step that copies the real binary into place never ran (--ignore-scripts, or npm 12 defaults). Which one you have decides the fix. I reproduced both on Claude Code 2.1.319 with npm 11.21.1 on Linux, and tested the fixes. The npm 12 part comes from Anthropic’s docs, because I did not have npm 12.

What the placeholder is

The @anthropic-ai/claude-code npm package is small. According to Anthropic’s install troubleshooting page, the real program is a per-platform optional dependency such as @anthropic-ai/claude-code-linux-x64, and a postinstall step copies it into place. Until both happen, claude is a placeholder that prints this:

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.

I saw exactly this text in both reproductions below. On Windows, the docs say the placeholder is a script saved as claude.exe, so PowerShell and CMD complain that they cannot run the file instead.

Step 1: find out which case you have

Look inside the folder that npm installed into (npm root -g for a global install, or the local node_modules):

ls node_modules/@anthropic-ai/
  • You see claude-code and claude-code-linux-x64 (or your platform’s name): the binary was downloaded, only the copy step was skipped. That is the --ignore-scripts case.
  • You see only claude-code: the platform package was never downloaded. That is the --omit=optional case.

This is what I got. With --ignore-scripts both folders were there, and after install.cjs the bin/claude.exe file was a real binary of about 340 MB. With --omit=optional, only claude-code existed and bin/claude.exe was a 500-byte placeholder.

Case A: scripts were skipped (platform package is present)

Run the postinstall by hand, as the message says:

node node_modules/@anthropic-ai/claude-code/install.cjs
claude --version

I tested this after npm install @anthropic-ai/claude-code --ignore-scripts. Before the fix claude printed the error. After it, claude --version printed 2.1.319 (Claude Code).

If you cannot run postinstall at all, the docs mention a fallback that finds the downloaded package and starts it, with an extra Node process on each launch:

node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs --version

That worked in my test too (it printed 2.1.319 (Claude Code)).

Case B: optional dependencies were skipped (platform package is missing)

Running install.cjs again cannot help, because there is no binary to copy. I tested it. The script said:

[@anthropic-ai/claude-code postinstall] Native package "@anthropic-ai/claude-code-linux-x64" not found.
  This happens with --omit=optional or when the download failed; re-run the install to fetch it.

and the wrapper said Could not find native binary package "@anthropic-ai/claude-code-linux-x64". The fix is to find what is switching optional dependencies off and reinstall.

  • Remove --omit=optional from your command (pnpm: --no-optional, Yarn: --ignore-optional).
  • Look for optional=false in your .npmrc. I tested this one: with optional=false in a project .npmrc, a plain npm install @anthropic-ai/claude-code installed only the claude-code folder, and npm config get omit printed optional. npm itself printed a config warning that suggests --omit=optional instead.
  • Check your registry. Anthropic’s docs say a corporate npm mirror must carry all eight platform packages as well as the main one.

Then reinstall (npm install -g @anthropic-ai/claude-code for a global install) and run claude --version.

npm 12 and the skipped postinstall (from the official docs)

I could not test this part. The docs say npm 12 finishes the install without running the postinstall step unless your config allows it. Check with npm --version; if it starts with 12, the docs give two ways out:

  • Switch to the native installer, then uninstall the npm copy. Updates then do not go through npm, so the error does not come back.
  • Stay on npm: if your version is 12.0.x, first upgrade to 12.1 or later (for example npm install -g npm@latest); after you save the allow-scripts setting, project installs started by an npx tool or an npm run script can fail with EALLOWSCRIPTS. Run npm config get allow-scripts first and note anything it lists, because the next command replaces the whole value. Then run npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user and reinstall. If that fails with EACCES, the docs say to use the native installer instead of sudo.

On my npm 11.21.1, a plain install printed a warning that Claude Code’s postinstall script is “not yet covered by allowScripts”, and the install still worked and put a 340 MB binary in place. Do not assume that stays true on npm 12.

If the error is still there

  • Make sure no old placeholder comes first on your PATH: type -a claude should list only the copy you want.
  • The docs list prebuilt binaries only for macOS, Linux (glibc and musl) and Windows on x64 and arm64. Other platforms, including FreeBSD, are not supported.
  • For a clean setup without npm, follow the Claude Code install guide. Other Claude Code messages are in the error list.

FAQ

Is the error caused by Claude Code being broken?

No. The program itself is fine. The install was incomplete.

Does sudo npm install -g fix it?

Not by itself. The cause is a skipped step, not permissions, and the docs advise against rerunning with sudo after an EACCES error.

What is the simplest way to avoid this for good?

The docs recommend the native installer: it does not go through npm, so there is no postinstall step to skip. Updates then also avoid npm.

Sources and test notes

  • Anthropic docs: Install troubleshooting, section “Native binary not found after npm install” (code.claude.com/docs/en/troubleshoot-install).
  • Tested myself: Claude Code 2.1.319 and npm 11.21.1 on Linux x64: --ignore-scripts, --omit=optional, optional=false in .npmrc, install.cjs, cli-wrapper.cjs, plain install.
  • Not tested: npm 12, pnpm, Yarn, macOS or Windows, corporate mirrors.

Leave a thought

Your email address will not be published.