Claude CodeにNode.jsは必要か — ネイティブ版は不要、npm版は22以上

Claude Codeを使うのにNode.jsが要るかどうかは、インストール方法によって答えが変わります。結論は、ネイティブインストーラーならNode.js不要で、npmでインストールする場合だけNode.js 22以上が必要というものです。

自分がどちらに当てはまるかの見分け方、Node.jsのバージョン確認と切り替え、claudeが動かないときの切り分けの順に進めます。OSやメモリなど全体の要件はClaude Codeのシステム要件にあります。

Node.jsが要るのはインストール方法がnpmのときだけ

Claude Codeの配布経路は大きく2系統です。

押さえたいのは、postinstallが走る通常の構成ではnpmで入れたあとのclaudeコマンドはNode.jsを呼び出さない点です。npmパッケージは@anthropic-ai/claude-code-darwin-arm64のようなプラットフォーム別のオプション依存パッケージとしてネイティブバイナリを取得し、postinstallスクリプトでそれを配置します。npmはインストーラーとして使われているだけです。

手元の実機で見ると

v2.1.287のネイティブ版をインストールした環境(Node.jsはv20.18.0、つまり22未満)で、実体とnpmの宣言を見た結果です。

$ claude --version
2.1.287 (Claude Code)
$ file "$(readlink -f "$(which claude)")"
~/.local/share/claude/versions/2.1.287: Mach-O 64-bit executable arm64
$ node -v
v20.18.0
$ npm view @anthropic-ai/claude-code engines
{ node: '>=22.0.0' }

claudeの実体はMach-Oの実行ファイルで、Node.js 20のままでも起動できています。要件の>=22.0.0は、パッケージのメタデータに書かれたenginesの値です。

npmでインストールする場合の必要バージョン

古いNode.jsでnpm install -g @anthropic-ai/claude-codeを実行すると、npmはEBADENGINEという警告を表示します。ただし、警告はインストールを失敗させません。インストールは完了し、claudeも起動します。

Node.jsのバージョンが効くのは、npmでインストール・アップグレードする瞬間だけです。アップグレードはnpm install -g @anthropic-ai/claude-code@latestで行います。npm update -gは元のインストール時のsemver範囲に従うため、最新版に上がらないことがあります。

sudo npm install -gは使いません。権限エラーとセキュリティリスクにつながるためで、権限エラーが出たらネイティブインストーラーへの切り替えが案内されています。対応プラットフォームはdarwin-arm64 darwin-x64 linux-x64 linux-arm64 linux-x64-musl linux-arm64-musl win32-x64 win32-arm64の8種類です。npmインストールには、パッケージマネージャーがオプション依存関係を許可している必要があります。

npm install -gで既存のnpmインストールをその場でアップグレードすると、以前のバイナリが削除されます。

インストール済みのNode.jsバージョンを確認する

ターミナルで次のコマンドを実行します。

node -v
npm -v

node -vがv22.x.x以上を返せば、npmインストールの要件を満たしています。command not foundが出る場合は、Node.js自体が未インストールか、PATHが通っていません。

WSLでは、LinuxではなくWindows側のNode.jsを拾っていることがあります。which nodeとwhich npmが/mnt/c/で始まればWindows側のバイナリで、Linux側なら/usr/などで始まります。この状態でclaudeを起動するとexec: node: not foundが出ます。これはWSL内でnpm install -gした場合の話で、ネイティブインストーラーで入れていれば該当しません。原因の詳しい切り分けはnode: not foundエラーの原因 — Claude Code WSLのnpmインストールにまとめています。

Node.jsのバージョンを切り替える

古いNode.jsしか入っていないときは、システムのNode.jsを更新するか、バージョン管理ツールで切り替えます。macOS・Linuxで広く使われているのはnvmです。

nvm install 22
nvm use 22
node -v

切り替えたあとは、npm install -g @anthropic-ai/claude-codeを再実行します。すでに動いているなら、再インストールは必須ではありません。次回のアップグレードでEBADENGINEが出なくなるだけです。

nvmでNodeを切り替えると、グローバルパッケージの置き場も変わります。公式のトラブルシューティングが載せるENOTEMPTYエラーの例では、パスが~/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/claude-codeのようにNodeのバージョン別でした。この例のように、エラーが指すディレクトリがnpm root -gの出力の下にないときは、エラーが示したディレクトリのほうを削除する、と案内されています。

ENOTEMPTYは、既存のインストールの上からnpm install -g @anthropic-ai/claude-codeを重ねたときに、npmが古いパッケージディレクトリを退避できず出るエラーです。npm error pathの行が示すディレクトリと、隣にある.claude-code-*の残骸を消してから、もう一度インストールします。macOS・Linuxの削除コマンドは次のとおりです。

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が入っていないかは、次の3か所で見分けます。

• ~/.local/bin/claude: ネイティブインストーラー
• ~/.claude/local/: 古いバージョンが作ったローカルのnpmインストール
• npm -g ls @anthropic-ai/claude-codeに出るもの: npmのグローバルインストール

nvmをWSLとWindowsの両方に入れている場合は、WSLがWindowsのPATHを引き継ぐ影響でWindows側のnvmが優先されることがあります。最も多い原因は、nvmがシェルに読み込まれていないことです。WSL特有の事情はClaude Code WSL2セットアップにまとめています。

Windowsネイティブ環境では、Unix系シェル前提のnvmはそのまま動きません。

MCPサーバーがNode.jsを要求するとき

Claude Code本体がNode.js不要でも、接続するMCPサーバー側が要求することがあります。公式のMCPの章では、claude mcp add --transport stdio myserver -- npx serverのようにnpx経由でサーバーを起動する例が目立ちます。claude mcp add --helpの例も-- npx my-mcp-serverです。

npxはnpmに同梱されたコマンドで、実行にはNode.js環境が要ります。ネイティブインストールで入れていても、npx -y @example/mcp-serverのようなサーバーを追加すれば、その起動にはローカルのNode.jsが必要になります。MCPサーバーが起動しないときは、Claude Codeのインストール方法より先に、システムにNode.jsが入っているかを見ます。

error: claude native binary not installedが出たときの切り分け

npmで入れたclaudeが動かないとき、原因をNode.jsのバージョンと決めつけると回り道になります。Error: claude native binary not installed.が出る場合は、次の順に見ます。

エラー全文は次のとおりです。

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.

このエラーはNode.jsのバージョンとは無関係に起こります。Node.js 22以上でも、--ignore-scripts付きで入れればプレースホルダーのまま止まります。

オプション依存関係が取れない原因は、上の設定のほかに2つあります。1つは、darwin-arm64など公式が配布する8種類のプラットフォームに該当しない環境であること。もう1つは、社内のnpmミラーが@anthropic-ai/claude-code-*のプラットフォーム別パッケージ8種を揃えていないことです。

Windows版では、npm経由のPowerShellでnpm.ps1やclaude.ps1がrunning scripts is disabled on this systemというSecurityErrorで止まることもあります。実行ポリシーが.ps1ランチャーを弾いているのが理由で、claude.cmdを呼ぶか、PowerShell用のネイティブインストーラーに切り替えると避けられます。

まとめ

ネイティブインストーラーで入れたなら、Node.jsの要否はnpxで動くMCPサーバーを使うかどうかだけで決まります。