native binary not installedエラーの原因と対処 — Claude Code
npmでインストールしたclaudeがnative binary not installedと出るのは、optional dependencyの省略が主な原因です。npm・pnpm・yarn別の直し方をまとめます。
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のどちらかが飛ばされると、プレースホルダーが残ったままになり、実行時にこのメッセージが出ます。
プラットフォームごとにパッケージを分けて配布しているのは、npmのoptional dependency機構の一般的な使い方です。単一のパッケージにすべてのOS・アーキテクチャ向けバイナリを同梱すると、利用者は自分の環境で使わない分までダウンロードすることになります。npmはpackage.jsonのoptionalDependenciesに列挙された依存関係のうち、自分の環境に一致しないものを自動的にスキップする仕組みを持っているため、通常はインストールする側が意識しなくても正しいバイナリだけが選ばれます。今回のエラーは、この「自動的に正しい1つだけを選ぶ」仕組みそのものが、フラグや設定によって丸ごと無効化されたときに表面化します。
Windowsでは症状の出方が異なります。bin/claude.exeも同じプレースホルダースクリプトですが、PowerShellやCMDはそれを実行可能ファイルとして認識できないため、このエラーメッセージ自体が表示されず「実行できないファイルです」という趣旨のOS標準のエラーになります。
原因1 — optional dependencyが無効化されている
ネイティブバイナリはoptional dependencyとしてのみ配布されているため、この設定が効いているとJavaScript側のフォールバックは存在せず、確実にこのエラーになります。パッケージマネージャーごとに該当するフラグが異なります。
| パッケージマネージャー | 無効化するフラグ | 対処 |
|---|---|---|
| npm | 無効化するフラグ--omit=optional | 対処フラグを外して再インストール |
| pnpm | 無効化するフラグ--no-optional | 対処フラグを外して再インストール |
| yarn | 無効化するフラグ--ignore-optional | 対処フラグを外して再インストール |
.npmrcにoptional=falseが設定されている場合も同じ原因になります。CI設定やDockerfileで使い回している.npmrcに紛れ込んでいないか確認してください。この場合はバイナリ自体がダウンロードされていないため、後述の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スクリプト自体を実行できない制約がある場合もあります。セキュリティポリシーでpostinstallを一律禁止しているCI環境や、サンドボックス化されたビルド環境が典型例です。その場合はcli-wrapper.cjsを使うと、ダウンロード済みのプラットフォームパッケージを探して起動できます。
node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjsただしこの方法は起動のたびに追加のNode.jsプロセスを介するため、常用より一時しのぎに向いています。cli-wrapper.cjsの実行時にCould not find native binary packageと出た場合は、プラットフォームパッケージ自体がダウンロードされていない状態です。原因はinstall.cjsの問題ではなく、前述のoptional dependency無効化の側にあるので、そちらを先に解消します。
原因3 — 対応していないプラットフォーム
プリビルドバイナリが提供されているのは次の8種類のみです。
darwin-arm64 / darwin-x64
linux-x64 / linux-arm64
linux-x64-musl / linux-arm64-musl
win32-x64 / win32-arm64これ以外のプラットフォームではネイティブバイナリ自体が存在しないため、どのフラグを調整しても解決しません。FreeBSDは対象外プラットフォームの代表例です。インストーラーはFreeBSDを未対応と正しく報告しますが、この判定自体が実装された時期は最近で、それより前のバージョンではFreeBSDをLinuxと誤認し、実行できないバイナリをダウンロードしてしまう不具合がありました。古いバージョンのインストーラーを使い続けている場合は、まずnpm install -g @anthropic-ai/claude-code@latestで最新化してから切り分けます。
原因4 — 社内npmミラーがプラットフォームパッケージを欠いている
企業内で社内npmレジストリをミラーとして使っている場合、@anthropic-ai/claude-code本体パッケージだけをミラーし、8種類のプラットフォーム別パッケージまでは同期していないケースがあります。この場合、開発者個人の設定は正しくても、レジストリ側にバイナリが存在しないため常にこのエラーになります。社内レジストリの管理者に、@anthropic-ai/claude-code-*で始まる8つのプラットフォームパッケージすべてがミラー対象に含まれているかを確認してもらう必要があります。
原因を絞り込む手順
上から順に確認すると無駄なく切り分けられます。
npm installのログにoptional関連の警告やスキップが出ていないか確認する- 使っているパッケージマネージャーの設定(
.npmrc・pnpmの設定ファイル・CI設定)で該当フラグが立っていないか確認する node_modules/@anthropic-ai/配下にclaude-code-<プラットフォーム名>ディレクトリが存在するか確認する。存在しなければ原因1か4、存在するのに動かなければ原因2- 自分のOS・アーキテクチャが対応8種類に含まれているか確認する
社内プロキシやミラー環境でどうしても切り分けが難しい場合は、ネイティブインストーラーへの切り替えが最も確実な回避策です。npmのoptional dependency解決自体に依存しない配布方式のため、この種のエラーは構造的に起きません。既存のnpmパッケージが残っていると、どちらのインストールが有効になっているか分かりにくくなるため、切り替える際はnpm uninstall -g @anthropic-ai/claude-codeで先に削除してから、ネイティブインストーラーを実行してください。設定ファイル(~/.claude/配下)はインストール方式を問わず共通なので、切り替えても引き継がれます。
よくある質問
install.cjsを実行しても直らないのはなぜですか
install.cjsはダウンロード済みのプラットフォームパッケージを配置する処理であり、パッケージ自体をダウンロードする処理ではありません。プラットフォームパッケージがそもそも存在しない場合(optional dependencyが無効化されている、またはミラーに無い場合)は、install.cjsを実行しても配置する実体がなく解決しません。
cli-wrapper.cjsを使い続けても問題ありませんか
動作はしますが、起動のたびに追加のNode.jsプロセスを経由するため、通常のインストールより起動が遅くなります。恒久的な運用には向かないので、postinstallが実行できない根本原因(実行環境のスクリプト制限など)を解消するか、フラグを外した再インストールを優先してください。
CIパイプラインで毎回このエラーが出ます
CI設定でnpm ci --omit=optionalのようなキャッシュ削減目的のフラグを使っている場合に起きやすいパターンです。Claude Codeを実行するジョブに限っては--omit=optionalを外すか、.npmrcでこのパッケージだけ例外にする必要があります。
Windowsで同じ原因のエラーは出ますか
出ますが表示のされ方が異なります。Windowsではbin/claude.exeもプレースホルダースクリプトのままなので、PowerShellやCMDが実行可能ファイルとして認識できず、このエラーメッセージではなく「このファイルは実行できません」という趣旨のOS標準のエラーになります。原因の切り分け手順自体はmacOS・Linuxと共通です。
node_modules/@anthropic-ai/配下に何も無い場合はどうすればいいですか
そのディレクトリ自体が存在しない、またはclaude-code本体パッケージしか無い場合は、プラットフォームパッケージがそもそもダウンロードされていません。原因1(optional dependency無効化)か原因4(社内ミラーの欠落)のどちらかです。npm installのログを再確認し、社内レジストリを使っている場合は管理者にミラー対象を確認してもらいます。
Dockerイメージのビルド時だけこのエラーが出ます
キャッシュ削減や再現性向上のためにnpm ci --omit=optionalやRUN npm config set optional falseをDockerfileに入れているケースが典型的な原因です。Claude Codeをイメージに含める場合は、その設定をこのパッケージのインストール行だけ除外するか、別レイヤーでフラグなしのインストールを行います。
まとめ
claude native binary not installedは、npmパッケージ本体とは別に配布されるプラットフォーム別のネイティブバイナリが、ダウンロードかpostinstallのどちらかの段階で欠落していることが原因です。--omit=optionalや--ignore-scripts系のフラグと.npmrcの設定をまず確認し、node_modules/@anthropic-ai/配下に該当プラットフォームのディレクトリがあるかで原因を切り分けます。対応外プラットフォームや社内ミラーの欠落が疑われる場合は、根本対処としてネイティブインストーラーへの切り替えを検討してください。npm・Homebrew・ネイティブの使い分けはClaude Code Homebrew・npm・ネイティブ導入の比較、WSL環境固有のnpmの落とし穴はClaude Code WSL2セットアップ、その他のインストールエラーはClaude Codeインストールエラーの切り分けチェックリストにまとめています。