native binary not installedエラーの原因と対処 — Claude Code

claude native binary not installedが出る仕組み

@anthropic-ai/claude-codeパッケージをnpmで入れてclaudeを実行すると、macOSとLinuxでは次のメッセージが出て起動しないことがあります。

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.

@anthropic-ai/claude-codeパッケージ本体はJavaScriptのプレースホルダースクリプトで、実際にコマンドを実行するネイティブバイナリは@anthropic-ai/claude-code-darwin-arm64のような、プラットフォームごとのoptional dependencyとして別途配布されています。npmはインストール時にそのバイナリをダウンロードし、続くpostinstallスクリプトがclaudeコマンドの実体としてバイナリを配置します。ダウンロードかpostinstallのどちらかが飛ばされると、プレースホルダーが残ったままになり、実行時にこのメッセージが出ます。

このバイナリはoptional dependencyとして届くため、パッケージマネージャーがoptional dependencyの取得を許可している必要があります。今回のエラーは、それがフラグや設定で無効化されたときに表面化します。

Windowsでは症状の出方が異なります。bin/claude.exeも同じプレースホルダースクリプトですが、PowerShellやCMDはそれを実行可能ファイルとして認識できず、このメッセージではなく「実行できないファイルです」という趣旨のOS標準のエラーになります。

まずnode_modulesを見る — 4つの確認で原因が決まる

症状から原因を決めるには、node_modules/@anthropic-ai/配下にclaude-code-<プラットフォーム名>ディレクトリがあるかが分かれ目になります。グローバルインストールならnpm root -gの出力の下を見ます。

原因1 — optional dependencyが無効化されている

ネイティブバイナリはoptional dependencyとしてのみ配布されているため、この設定が効いているとJavaScript側のフォールバックは存在せず、確実にこのエラーになります。

.npmrcにoptional=falseが設定されている場合も同じ原因になります。使い回している.npmrcやCI設定に紛れ込んでいないか確認してください。この場合はバイナリ自体がダウンロードされていないため、install.cjsを手動実行しても効きません。配置するものがないためです。設定を外して再インストールします。

原因2 — postinstallスクリプトが実行されていない

--ignore-scriptsや一部のpnpm設定は、プラットフォームパッケージはダウンロードしつつ、postinstallだけをスキップします。バイナリはすでにディスク上にあるので、postinstallを手動で実行すれば直ります。

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

グローバルインストールの場合はパスを読み替えます。npm root -gの出力に@anthropic-ai/claude-codeを続けたパスが該当します。フラグを外して再インストールしても直ります。

セキュリティポリシーでpostinstallを一律禁止しているCI環境のように、スクリプトをそもそも実行できない環境ではcli-wrapper.cjsが使えます。ダウンロード済みのプラットフォームパッケージを探して起動します。

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

起動のたびに追加のNode.jsプロセスを介するため、常用より一時しのぎ向きです。実行時にCould not find native binary packageと出たら、プラットフォームパッケージ自体がダウンロードされていません。install.cjsではなく原因1・4の側を先に解消します。

原因3 — 対応していないプラットフォーム

プリビルドバイナリが提供されているのは次の8種類のみです。

darwin-arm64 / darwin-x64
linux-x64 / linux-arm64
linux-x64-musl / linux-arm64-musl
win32-x64 / win32-arm64

これ以外ではネイティブバイナリ自体が存在せず、どのフラグを調整しても解決しません。FreeBSDが代表例で、インストーラーは未対応と報告します。v2.1.205より前のバージョンはFreeBSDをLinuxと扱い、実行できないバイナリをダウンロードしていました。古いインストーラーを使っているなら、まずnpm install -g @anthropic-ai/claude-code@latestで最新化してから切り分けます。Android上のTermuxも対応外の環境です(詳しくはTermuxでClaude Codeが動かない理由)。

原因4 — 社内npmミラーがプラットフォームパッケージを欠いている

社内npmレジストリをミラーとして使っている場合、@anthropic-ai/claude-code本体だけをミラーして、8種類のプラットフォーム別パッケージが欠けていることがあります。個人の設定が正しくても、レジストリ側にバイナリが無ければ常にこのエラーです。管理者に、@anthropic-ai/claude-code-*で始まる8つすべてがミラー対象かを確認してもらいます。

CIとDockerでだけ出るとき

手元では動くのにCIやイメージのビルドでだけ出るなら、そのジョブの設定を疑います。npm ci --omit=optionalが入っている、またはRUN npm config set optional falseのように.npmrc相当の設定をDockerfileに書いていれば、原因1と同じです。

Claude Codeをインストールする行だけフラグを外すか、別レイヤーでフラグなしのインストールを行います。フラグを外せない事情があるなら、原因2の範囲でcli-wrapper.cjsを経由する手もありますが、プラットフォームパッケージがダウンロードされていることが前提です。

npmを抜けてネイティブインストーラーに切り替える

npmのoptional dependency解決に依存しない配布方式に切り替えれば、この種のエラーは前提から外れます。v2.1.285のヘルプでは、この経路がclaude installとして出ます。

claude install --help

Usage: claude install [options] [target]
 
Install Claude Code native build. Use [target] to specify version (stable,
latest, or specific version)
 
Options:
  --force     Force installation even if already installed
  -h, --help  Display help for command

targetにはstable・latest・具体的なバージョンを渡せます。ただしclaudeが起動しない状態ではこのコマンド自体を実行できないので、npm版が壊れているときの入口にはなりません。入口は公式のインストールスクリプトで、macOSとLinuxでは次のコマンドです。Windows PowerShellではirm https://claude.ai/install.ps1 | iexを使います。

curl -fsSL https://claude.ai/install.sh | bash

切り替えるときは、どちらのclaudeが有効か分からなくなる混乱を避けるため、npm uninstall -g @anthropic-ai/claude-codeで先にnpm版を消してから、ネイティブ版を入れます。

ネイティブ版を入れたあとの姿はv2.1.285のmacOSで確認しました。which claudeは~/.local/bin/claudeを返し、それはバージョンごとのバイナリへのシンボリックリンクです。

$ claude --version
2.1.285 (Claude Code)
 
$ ls -l "$(which claude)"
... /.local/bin/claude -> ~/.local/share/claude/versions/2.1.285

npmのグローバル領域(npm ls -g --depth=0で確認)にはcorepackとnpmしか載っておらず、node_modules/@anthropic-ai/配下に置かれる本体もありません。この状態では、プラットフォームパッケージの欠落という原因は起こりようがありません。導入後の状態はclaude doctorで確認できます。

claude doctor --help

Usage: claude doctor [options]
 
Check the health of your Claude Code installation. Reads settings files in the
current directory without a trust prompt. For a full checkup that can also fix
issues, run /doctor in a session.

なお、切り替えても直らないエラーもあります。起動時にIllegal instructionと出る場合は、原因が2つあります。1つはアーキテクチャの不一致で、ARMサーバーにx86版が入った場合などです。uname -m(PowerShellでは$env:PROCESSOR_ARCHITECTURE)の結果が入ったバイナリと合わなければ、出力を添えてGitHub issueに報告します。もう1つはCPUが必要な命令に対応していないことで、npmを含むどのインストール方法も同じネイティブバイナリをダウンロードするため解決しません。こちらは、AVX命令のない古いCPUや、AVXをゲストに渡さない仮想マシンで起きます。VPSではgrep -m1 -ow avx /proc/cpuinfoが空なら、AVXが使えない環境です。

npmで更新するとENOTEMPTYで止まるとき

同じnpm経由でも、npm install -g @anthropic-ai/claude-codeを既存のインストールに重ねると別のエラーで止まることがあります。npm error code ENOTEMPTYとrenameが出て、npm error pathの行に移動できなかったディレクトリが示される型です。

対処は、そのディレクトリと、隣にある.claude-code-で始まる残骸を消してから再インストールすることです。

rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*

Windows PowerShellでは次のコマンドです。

Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"

Zshでno matches foundと出たら、消すものが無かったという意味です。nvmでNodeのバージョンを切り替えていてnpm error pathがnpm root -gの下でない場合は、エラーが示すディレクトリのほうを消します。原因はnative binaryの欠落とは別なので、このエラーが出ても原因1〜4を疑う必要はありません。

まとめ

npm自体をやめてよい環境なら、npmを抜けてネイティブ版に移すのが切り分けの手間も含めて最短です。ただしclaudeが起動しないうちはclaude installが使えないので、公式のインストールスクリプトから入ります。npm・Homebrew・ネイティブの使い分けはClaude Code Homebrew・npm・ネイティブ導入の比較、WSL環境のnpmの落とし穴はClaude Code WSL2セットアップ、ほかのインストールエラーはClaude Codeインストールエラーの切り分けチェックリストにあります。Claude Code全体の導入は完全ガイドを参照してください。