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.

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-codeandclaude-code-linux-x64(or your platform’s name): the binary was downloaded, only the copy step was skipped. That is the--ignore-scriptscase. - You see only
claude-code: the platform package was never downloaded. That is the--omit=optionalcase.
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=optionalfrom your command (pnpm:--no-optional, Yarn:--ignore-optional). - Look for
optional=falsein your.npmrc. I tested this one: withoptional=falsein a project.npmrc, a plainnpm install @anthropic-ai/claude-codeinstalled only theclaude-codefolder, andnpm config get omitprintedoptional. npm itself printed a config warning that suggests--omit=optionalinstead. - 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 theallow-scriptssetting, project installs started by annpxtool or annpm runscript can fail withEALLOWSCRIPTS. Runnpm config get allow-scriptsfirst and note anything it lists, because the next command replaces the whole value. Then runnpm config set "allow-scripts=@anthropic-ai/claude-code" --location=userand reinstall. If that fails withEACCES, the docs say to use the native installer instead ofsudo.
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 claudeshould 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=falsein.npmrc,install.cjs,cli-wrapper.cjs, plain install. - Not tested: npm 12, pnpm, Yarn, macOS or Windows, corporate mirrors.