Claude を npm でインストール｜sudo NG・@latest 更新の注意点

Claude Code は npm でも入る — 公式提供の Node.js 経路

Claude Code(claude コマンド)は Anthropic 公式の npm パッケージ @anthropic-ai/claude-code として配布されており、Node.js 18 以上が入った環境であれば npm install -g @anthropic-ai/claude-code で導入できます出典。npm 経路の特徴は、Node.js プロジェクトをすでに運用しているチームにとって導入手順を増やさずに済む点と、CI / Docker イメージなど node がある場所であれば再現性高くセットアップできる点です。

ただし重要な前提として、npm パッケージは JavaScript で書かれた CLI ではありません。配布されるのはプラットフォーム別の ネイティブバイナリへのラッパー で、darwin-arm64 等のサフィックスを持つ optional dependency 経由でバイナリをプルし、ポストインストール時にリンクを張ります。インストール後の claude 実行時は Node.js を一切呼ばない ため、起動オーバーヘッドはネイティブインストーラ版と同等です。

つまり npm 経路は「配布チャネルとしての npm を使うが、実体はネイティブバイナリ」という設計で、Homebrew や WinGet 経路と本質的に同じバイナリが手に入ります。違いは更新の自動化と PATH の置かれ方だけです。

動作要件 — Node.js 18 以上と対応 8 プラットフォーム

npm 経由でインストールする場合の最低要件は以下です出典。

• Node.js: 18 以上(LTS 推奨)
• OS: macOS 13.0 以降 / Windows 10 1809 以降 / Ubuntu 20.04 以降 / Debian 10 以降 / Alpine Linux 3.19 以降
• RAM: 4 GB 以上
• サブスクリプション: Claude Pro / Max / Team / Enterprise / Anthropic Console のいずれか

Anthropic がプリビルドして配布しているネイティブバイナリは 8 種類で、darwin-arm64(Apple Silicon Mac)・darwin-x64(Intel Mac)・linux-x64・linux-arm64・linux-x64-musl・linux-arm64-musl・win32-x64・win32-arm64 をカバーします。Apple Silicon Mac から ARM64 Windows まで主要環境を網羅しており、ラズパイの 32bit や、AVX 命令を持たない 2013 年以前の Intel / AMD CPU など、これ以外のプラットフォームは対象外です。

サブスクリプション要件は npm 経路でも例外なく適用され、Claude.ai 無料プランでは認証が通りません。請求アカウントの状態は事前に claude.ai/settings で確認しておくと、インストール後に 403 Forbidden で詰まる事故を避けられます。

インストールコマンドと初回認証 — npm install -g から claude 起動まで

実際の導入はワンライナーです出典。

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

インストール完了後、任意のプロジェクトディレクトリで claude を実行するとブラウザが立ち上がり、OAuth ログインに遷移します。ブラウザが自動で開かない SSH / WSL2 / Docker 環境では、対話プロンプトで c を押すと OAuth URL がクリップボードにコピー されるので、それを手元のブラウザで開いてください。

リモートホストで作業しているケースでは、ブラウザがリダイレクトする先がローカルマシンになるため、ログイン後に表示される コードを手で貼り付け て認証を完了します。コードが反映されない場合は claude auth login を使うと標準入力からコードを読めるため、貼り付けの仕様差を回避できます。

ログイン後に claude doctor を一度走らせると、PATH・Keychain・Node.js バージョン・ネットワーク到達性が一気に診断できます。インストール直後にこれを通しておくと、初回トラブルを事前に潰せます。

sudo を使わない理由 — nvm / Volta でユーザー領域に置く

npm 経路で最も多い事故が、sudo npm install -g @anthropic-ai/claude-code を叩いてしまうことです。Anthropic 公式は 「sudo を使ってはいけない」 と明示しており、root 領域へのグローバルインストールはパーミッション破壊・セキュリティリスク・後続コマンドでの権限不整合を呼び込みます出典。

解決策は Node.js 自体を ユーザー領域のバージョンマネージャ で管理することです。代表的な選択肢は以下です。

• nvm(Node Version Manager): ~/.nvm 配下に Node を置き、sudo なしで -g 可能
• Volta: Rust 製の高速 Node マネージャ、プロジェクト毎のバージョン固定が強い
• asdf + nodejs プラグイン: 複数言語のバージョンを統括する場合

どれを選んでも、which node の結果が /usr/bin/node や /usr/local/bin/node ではなく ~/.nvm/versions/node/... のようにホームディレクトリ配下を指していれば、npm install -g は sudo なしで通ります。すでに /usr/local の Node を使っている場合は、一度アンインストールして nvm 等に置き換えるのが長期的に安全です。

なお、過去に sudo で入れた @anthropic-ai/claude-code が残っているとパーミッションエラーで止まることがあります。その場合は sudo npm uninstall -g @anthropic-ai/claude-code でいったん消去してから、ユーザー権限で入れ直してください。

アップデートは @latest 指定 — npm update -g が動かない理由

Claude Code は週次に近いペースで更新が入るため、定期的なアップデートが事実上必須です。npm 経路で更新する場合の 唯一の正解 は以下です出典。

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

ここでよくある誤りが npm update -g を叩いてしまうケースです。Anthropic は明示的に 「npm update -g は使わないでください」 と書いており、理由は npm の update コマンドが 元のインストール時の semver 範囲を尊重 するため、本来取りに行ってほしい最新版に届かない可能性があるからです。

実務的には @latest を毎回付けるエイリアスを作っておくか、.zshrc / .bashrc に以下のような関数を入れておくと運用が安定します。

claude-up() {
  npm install -g @anthropic-ai/claude-code@latest
  claude --version
}

更新後は必ず claude --version でバージョン番号を確認し、想定どおり上がっているかを目視するクセを付けてください。Claude Desktop アプリが Windows で WindowsApps の旧 Claude.exe を残している場合、PATH の優先順位で旧版が呼ばれることがあり、--version の確認で初めて気付くことがあります。

自動更新を有効化する — CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1

ネイティブインストーラ経路では Claude Code が自動でバックグラウンド更新を回しますが、npm 経路はデフォルトで自動更新が無効 です出典。Homebrew と WinGet は CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 環境変数で自動更新を on にできますが、npm はこのフラグでも自動更新は走りません。これは npm にバックグラウンドプロセスを常駐させる仕組みがないためです。

したがって npm で運用する場合は、以下のいずれかを選ぶ必要があります。

• 手動更新: 週次〜隔週で npm install -g @anthropic-ai/claude-code@latest を叩く
• cron / Scheduled Task: 上記コマンドを定期実行に登録(再起動不要)
• 乗り換え: 自動更新が必要ならネイティブインストーラに切り替え

CI / Docker イメージで使うケースでは、Dockerfile で npm install -g @anthropic-ai/claude-code@latest を指定しておけばイメージビルド時点で常に最新が入るため、自動更新の概念自体が不要になります。

Native binary not found — optionalDependencies の罠と社内 registry

npm install -g @anthropic-ai/claude-code が表面上は成功したのに、claude を起動すると Could not find native binary package "@anthropic-ai/claude-code-<platform>" というエラーで止まるトラブルがあります出典。原因は 3 パターンです。

1. optional dependencies が無効化されている: npm install に --omit=optional、pnpm に --no-optional、yarn に --ignore-optional が付いていないか確認。.npmrc に optional=false が書かれているとサイレントに無効化されるので注意
2. 対応外プラットフォーム: 8 種以外の OS / アーキテクチャでは配布されていない
3. 社内 npm registry のミラー不足: meta パッケージはミラーされていても、8 つの @anthropic-ai/claude-code-* プラットフォームパッケージが揃っていないと取得失敗

社内 registry を使っている企業ユーザーは特に 3 番で詰まりやすく、情シスに依頼して 8 種すべての platform package をミラー してもらう必要があります。なお --ignore-scripts を付けるとポストインストールのリンク処理がスキップされ、Claude Code は起動時にバイナリを探し直すラッパーモードで動きます。動きはしますが起動が遅くなるため、可能ならスクリプト有効でインストールし直してください。

WSL での npm 落とし穴 — Windows nvm との競合

Windows + WSL2 環境で開発している場合、npm 経路には固有の罠が 3 つあります出典。

1. WSL から Windows の npm を拾う: npm config set os linux で OS を明示し、npm install -g @anthropic-ai/claude-code --force で再インストール
2. exec: node: not found: which npm / which node の結果が /mnt/c/ で始まっていれば Windows の Node を拾っている証拠。Linux 側の nvm で Node を入れ直す
3. nvm が Windows と WSL で競合: WSL の ~/.bashrc に NVM_DIR 設定が無いと Windows nvm が優先される。下記ブロックを .bashrc に追加

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

それでも Windows パスが優先される場合は、明示的に Linux Node を PATH の先頭に置きます。

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

appendWindowsPath = false で Windows PATH を完全に切るのは、WSL から Windows 実行ファイルを呼べなくなるため推奨されません。Windows 側の nvm をアンインストールするのも、Windows 側の Node 開発を壊すリスクがあるため避けるのが無難です。

アンインストールと旧 local install のクリーンアップ

npm 経路で入れた Claude Code を消す場合は以下です出典。

npm uninstall -g @anthropic-ai/claude-code

設定ファイルまで完全に削除する場合は、macOS / Linux で以下を追加実行します。

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

ここで見落としやすいのが、古い Claude Code が ~/.claude/local/ に local npm install を残している ケースです。これは旧バージョンが採用していた配布方式の名残で、新しいネイティブインストーラに乗り換えた後も残骸が PATH を奪うことがあります。ls -la ~/.claude/local/ で確認し、不要なら rm -rf ~/.claude/local で削除してください。

Windows では PowerShell で Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local" を実行します。which -a claude(macOS / Linux)や where.exe claude(Windows)で複数の claude が見えたら、PATH の優先順位による混乱が起きる前にどちらかを消すのが鉄則です。

他経路との比較 — ネイティブ・Homebrew・WinGet との違い

最後に、npm 経路を選ぶべき場面とそうでない場面を整理します。

npm 経路は 「すでに Node.js が動いている開発機」「再現性ある CI / Docker イメージ」「複数言語の中で npm を中心に管理しているチーム」 に最適です。一方、個人 PC で「ただ使いたいだけ」なら自動更新付きのネイティブインストーラの方が運用負担が軽く、Anthropic 公式も推奨経路として最初に挙げています。

迷ったら次のフローで選んでください。

1. CI / Docker / Node プロジェクトに混ぜたい → npm
2. 自動更新が欲しい個人 PC(macOS / Windows) → ネイティブインストーラ
3. brew / winget 中心の管理運用 → Homebrew / WinGet

OS 横断の経路比較とトラブルシューティング全般はClaude CLI のインストール、Windows 専用の経路選びはClaude を Windows にインストールも併読すると、自分の環境に最も合うルートが選べます。