npm warn EBADENGINEの意味と対処 — Claude Codeの警告は無視してよいか

Claude CodeのEBADENGINE警告とは

npm install -g @anthropic-ai/claude-code を実行したとき、手元のNode.jsが22未満だと、npmは次のような EBADENGINE 警告を表示します。

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '@anthropic-ai/claude-code@x.x.x',
npm warn EBADENGINE   required: { node: '>=22.0.0' },
npm warn EBADENGINE   current: { node: 'v18.20.4', npm: '10.7.0' }
npm warn EBADENGINE }

各行の意味は次のとおりです。package は入れようとしているパッケージ、required はそのパッケージが engines フィールドで宣言しているNode.jsの範囲、current は今動いているNode.jsとnpmのバージョンです。required と current が食い違うと、npmがこの EBADENGINE を出します。行頭が npm warn なら警告、npm error code EBADENGINE なら停止で、分かれ目は後述の engine-strict です。

npm warn の場合、これはエラーではありません。インストールはそのまま最後まで完了し、claude コマンドも問題なく動きます。npmパッケージのNode.js要件が22以降に引き上げられたのはv2.1.198です。

それ以前も要件がなかったわけではありません。npmレジストリのメタデータでは、v2.1.197までの engines は node: >=18.0.0 で、v2.1.198から >=22.0.0 になっています。Node.js 18〜21を使い続けている環境では、パッケージ側の基準が上がったことで、同じ手順のインストールに警告が出るようになりました。すでに入れて問題なく使えていたClaude Codeが、ある日から警告を出すようになった場合の原因もここにあります。

nvmで複数のNode.jsバージョンを切り替えている環境では、プロジェクトごとに古いバージョンをアクティブにしたままClaude Codeを入れ直すことがあり、そのたびにこの警告を目にすることになります。結論から言うと、警告を消すための作業は必須ではありません。ただしnvmとの組み合わせでは、警告以外に動作へ本当に影響する別の落とし穴もあるため、区別して理解しておく価値があります。

警告が出る前に確認しておくこと

インストールコマンドを実行する前に、現在アクティブなNode.jsのバージョンを確認しておくと、警告が出た理由をすぐに特定できます。

node --version
nvm current

node --version が v22 未満を返していれば、EBADENGINE警告が出るのは想定通りです。nvm current の結果が system(nvm管理外のNode.js)になっている場合は、nvmでインストールしたバージョンではなくOS標準のNode.jsを参照しています。この場合は nvm use で切り替えてから、あらためてバージョンを確認します。

同じNode.jsで警告になる場合とエラーになる場合

Node.js v20.18.0 / npm 10.8.2の環境でv2.1.289を一時ディレクトリへ --dry-run で入れると、何も指定しなければ警告が出て、依存パッケージの追加予定は最後まで進みます。

npm install @anthropic-ai/claude-code@2.1.289 --dry-run --ignore-scripts

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '@anthropic-ai/claude-code@2.1.289',
npm warn EBADENGINE   required: { node: '>=22.0.0' },
npm warn EBADENGINE   current: { node: 'v20.18.0', npm: '10.8.2' }
npm warn EBADENGINE }
add @anthropic-ai/claude-code-win32-x64 2.1.289
add @anthropic-ai/claude-code-linux-x64-musl 2.1.289
（以下、プラットフォーム別パッケージの add が続く）

--engine-strict を付けると、同じ環境で同じパッケージが EBADENGINE エラーになり、依存の追加に進みません。

npm install @anthropic-ai/claude-code@2.1.289 --dry-run --engine-strict

npm error code EBADENGINE
npm error engine Unsupported engine
npm error notsup Required: {"node":">=22.0.0"}
npm error notsup Actual:   {"npm":"10.8.2","node":"v20.18.0"}

どちらの状態かは npm config get engine-strict で確かめられます。true が返る環境で警告を読み飛ばす選択肢はなく、Node.jsを22以上に上げるか、engine-strict を無効にするか、後述するネイティブインストーラーに切り替えます。

v2.1.197を同じ条件で入れると、EBADENGINE は出ません。要件が18のままだったためです。

なぜNode.js 22未満でもclaudeコマンドは動くのか

EBADENGINE警告が実害を伴わない理由は、npmパッケージの中身にあります。@anthropic-ai/claude-code はJavaScriptで書かれた実装ではなく、ネイティブインストーラーと同じネイティブバイナリを配布するための入れ物です。

npmはインストール時に @anthropic-ai/claude-code-darwin-arm64 のようなプラットフォーム別のオプション依存パッケージを取得します。postinstallスクリプトがそのバイナリを claude コマンドとして配置する仕組みです。インストールされたclaudeバイナリ自体はNode.jsを呼び出しません。実行時にはOSネイティブのプロセスとして動くため、インストール時に使ったNode.jsのバージョンは起動後の挙動に影響しません。

engines フィールドのチェックは、あくまでnpmが行う静的な検査です。パッケージの実行内容とは別物です。ここがEBADENGINE警告を安全に読み飛ばせる根拠になります。対応プラットフォームは darwin-arm64 / darwin-x64 / linux-x64 / linux-arm64 / linux-x64-musl / linux-arm64-musl / win32-x64 / win32-arm64 の8種類です。これに該当する環境であれば、警告の有無にかかわらずバイナリは正しく配置されます。

インストールが正しく完了したかどうかは claude doctor で確認できます。claude doctor はインストールの状態を読み取り専用で診断します。EBADENGINE警告が出ていても、claude --version が通れば動作に問題はありません。逆に claude コマンド自体が見つからない場合は、警告とは別の原因を疑う必要があります。

警告ではなく本当に壊れるのはpostinstallが動かないとき

npmパッケージの claude は、postinstallが実バイナリへ差し替えるまで、プレースホルダーのスクリプトです。プラットフォーム別パッケージの取得か、postinstallの実行のどちらかが飛ぶと、差し替えが起きません。

原因は --ignore-scripts(一部のpnpm設定を含む)か、--omit=optional と optional=false の .npmrc です。Node.jsのバージョンとは関係なく、Node.js 22以上でも起こります。macOSとLinuxでは claude の実行時に、次のメッセージが出ます。

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).

Windowsでは bin/claude.exe がこのプレースホルダー自体で、上のメッセージではなく「実行できない」という趣旨のエラーが出ます。

nvmでNode.jsを22以上に上げる場合

警告そのものは無視してよいものの、Node.js自体を新しくしておくメリットはあります。他のCLIツールやプロジェクトの engines 要件を満たしやすくなり、npmの警告ログが増えるのも避けられます。nvmでの上げ方はシンプルです。

nvm install 22
nvm alias default 22
nvm use 22

nvm alias default を設定すると、新しいシェルを開いたときにも22系が自動的にアクティブになります。プロジェクト単位でバージョンを固定したい場合は、リポジトリ直下に .nvmrc を置いて 22 と書いておきます。以後は引数なしの nvm use だけで、そのプロジェクト用のバージョンに切り替わります。

Node.jsを上げたあとにClaude Codeを入れ直す必要はありません。すでにインストール済みの claude バイナリはNode.jsのバージョンに依存しないためです。警告が出るのは、npmがインストールを実行する時点のNode.jsが22未満のときだけです。

npm install -g @anthropic-ai/claude-code@latest

アップデート時は npm update -g ではなく、@latest を明示したこのコマンドを使います。npm update -g は最初にインストールしたときのsemver範囲に従うため、最新版に上がらないことがあります。sudo npm install -g は権限エラーやセキュリティ上のリスクにつながるため避けます。

nvmでバージョンを切り替えるとclaudeコマンドが消える理由

EBADENGINE警告より実害が大きいのは、nvmの仕組みそのものに由来する別の現象です。nvmの仕様上、Node.jsのバージョンごとに独立したグローバル node_modules ディレクトリを持ちます。あるバージョンで npm install -g @anthropic-ai/claude-code を実行すると、claude バイナリはそのバージョン専用のディレクトリ配下に配置されます。

その後 nvm use で別のバージョンに切り替えると、PATHが参照するグローバルディレクトリごと変わります。結果として command not found: claude になることがあります。実体が消えたわけではなく、切り替え前のバージョンに戻せば claude は再び見つかります。プロジェクトごとに .nvmrc で異なるNode.jsバージョンを指定しているチームほど踏みやすい落とし穴です。

この構造的な問題を避けたいなら、Node.jsのバージョン管理と無関係に動くネイティブインストーラーに切り替える選択肢があります。

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

ネイティブインストーラーは ~/.local/bin/claude にバイナリを配置し、nvmが管理するNode.jsのディレクトリ構造とは完全に独立します。npmでのグローバルインストールが既に残っている場合は、npm uninstall -g @anthropic-ai/claude-code で削除しておくと、which -a claude で複数の実体が引っかかって挙動が安定しない状態を避けられます。

早見表 — 状況ごとの対応

表示されたメッセージやコマンドの結果から、該当する行を探してください。対応の必要な症状とそうでない症状が混在するため、まず切り分けることが重要です。

アップデートでENOTEMPTYが出た場合

nvm環境固有のもう一つのつまずきとして、npm install -g @anthropic-ai/claude-code を再実行してアップデートしようとした際に、ENOTEMPTY エラーで失敗するケースがあります。

npm error code ENOTEMPTY
npm error syscall rename
npm error path /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/claude-code
npm error dest /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/.claude-code-tVWAnUUt

npm error path の行が、npmが移動に失敗したディレクトリを示しています。中断されたインストールが残した一時ディレクトリが原因になっていることが多く、npm root -g が返すパス配下でそのディレクトリを削除してから再インストールすれば解消します。nvmでNode.jsバージョンを切り替えた直後は、npm root -g の出力先とエラーメッセージのパスがずれることがあります。その場合はエラーメッセージが示すパスをそのまま削除対象にします。

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

削除後に claude --version を実行し、バージョン番号が表示されればインストールは成功しています。表示されなければ、npm root -g が指すディレクトリ自体が想定と違う可能性があるため、node --version と nvm current で今アクティブなNode.jsを再確認します。

まとめ

EBADENGINE警告は、Node.js 22未満の環境で npm install -g @anthropic-ai/claude-code を実行したときに出る想定内の警告です。claude バイナリはネイティブバイナリとして動作しNode.jsを呼び出さないため、警告を放置してもインストールと動作の両方が完了します。

一方でnvmを使ったバージョン管理そのものは、グローバルインストールがNode.jsバージョンごとに独立するという別の性質を持ちます。こちらは claude コマンドが見つからなくなる実害につながります。頻繁にNode.jsのバージョンを切り替える開発環境では、Claude Code自体はネイティブインストーラーに切り替えてしまうほうが、この種の管理コストを避けられます。

OSごとのインストール手順全体はClaude Code install完全ガイドにまとめています。WSLでnvmとWindows側のNode.jsが競合してnode: not foundになる別の症状はnode: not foundエラーの原因で扱っています。EBADENGINE以外のインストールエラーに遭遇した場合は、Claude Codeインストールエラーの切り分けチェックリストからエラーメッセージ別に原因を絞り込めます。