Claude Media
Claude CodeをHomebrewで入れる方法と更新 — npm・ネイティブとの比較

Claude CodeをHomebrewで入れる方法と更新 — npm・ネイティブとの比較

Homebrewでは安定版のclaude-codeと最新版のclaude-code@latestを選んで入れます。npm・ネイティブとの更新方式の違いと、混在時の不具合の直し方を扱います。

Claude CodeをHomebrew・npm・ネイティブのどれで入れるか

Claude Codeは、どの経路で入れても配置されるバイナリ自体は同じネイティブバイナリです。違うのは配布経路と更新の仕組みだけで、選び方を誤ると起きるのは機能差ではなく運用トラブルです。気づかないうちに古いバージョンのまま止まる、複数経路が競合してバージョンがずれる、といった形で表に出ます。

Homebrewで入れるコマンドは、安定版なら次のとおりです。最新版が欲しいときは、末尾を claude-code@latest に替えます。

brew install --cask claude-code
brew install --cask claude-code@latest

2行は同時に実行するものではありません。どちらか1つを選びます。

OS別のインストールコマンドはClaude Codeインストール完全ガイドにまとめてあります。本記事は更新方式の違いと、経路を混在させたときに何が壊れるかに絞ります。brew upgradeの直後にバックグラウンドセッションが開かなくなった場合はbrew upgrade後のENOENTの対処を参照してください。自作CLIをHomebrewで配る側の手順はClaude CodeでHomebrewのformulaとtapを作る手順にあります。

3つの経路は更新の仕組みがこう違う

3経路

経路ごとの更新方式

  • ネイティブインストーラー

    curl | bash(macOS/Linux/WSL2)または irm | iex(Windows)で入れます。バックグラウンドで自動更新され、autoUpdatesChannel で latest か stable を選べます。

  • Homebrew(macOS)

    claude-code が安定版、claude-code@latest が最新版のcaskです。更新は手動で、チャネルはcask名で決まります。

  • npm

    @anthropic-ai/claude-code を npm install -g で入れます。Node.js 22以上が前提で、更新は npm install -g @anthropic-ai/claude-code@latest です。

WinGetとapt・dnf・apkも既定は手動更新で、Homebrewと同じ側に入ります。WinGetだけは次の節の環境変数が使えます。

比較点ネイティブHomebrewnpm
バージョン指定ネイティブclaude install <version> やinstall.shの引数Homebrewcaskの選択のみnpm@バージョン 指定
つまずきやすい点ネイティブ少ないHomebrewcaskのインデックスが古いnpmoptional dependencyが無効だとバイナリが入らない

古いNode.jsでは EBADENGINE の警告が出るだけでインストールは完了し、claude も動きます。npmが取得するのはプラットフォーム別のネイティブバイナリで、実行時にNode.jsを使わないためです。

Homebrewの更新を自動にしたい・止めたいとき

手動で更新するコマンドは brew upgrade claude-code です。最新版caskなら brew upgrade claude-code@latest を使います。

CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE を 1 にすると、新しいバージョンがあるときにClaude Code自身がバックグラウンドでアップグレードを実行し、成功すると再起動を促します。対象はHomebrewとWinGetだけです。この操作で影響を受けるのはClaude Codeのパッケージだけで、ほかのソフトには触れません。WinGetでは実行中の実行ファイルがWindowsにロックされて失敗することがあり、その場合は手動コマンドが表示されます。apt・dnf・apkは管理者権限が要るため、この変数でも自動にはなりません。

逆に更新を止めたい場合は、似た名前の変数が2つあります。

くらべる

更新を止める2つの変数

バックグラウンドだけ止める

DISABLE_AUTOUPDATER

1 にすると自動更新だけが止まります。claude update と claude install は使えます。

手動更新も止める

DISABLE_UPDATES

claude update と claude install も含めてすべての更新経路を塞ぎます。自社の配布経路でバージョンを管理したいときに使います。

Homebrewの「新しさ」を決めるのは、この変数ではなくcask名です。claude-code は最新から約1週間遅れで、大きな不具合のあるリリースを飛ばします。最新版が欲しいなら claude-code@latest を選びます。

入れた経路が分からないときの調べ方

複数の経路で重ねて入れると、claude コマンドがどのバイナリを指すかが分かりにくくなり、バージョンのずれや更新の効かない状態を招きます。以前npm版を使っていた環境にネイティブインストーラーを追加したケースが典型です。

claude が来る可能性のある場所は3つあります。~/.local/bin/claude がネイティブ、~/.claude/local/ が旧バージョンの作ったローカルnpm、そしてnpmのグローバル一覧に載る -g 版です。

which -a claude
npm -g ls @anthropic-ai/claude-code 2>/dev/null
ls ~/.claude/local/ 2>/dev/null
ls -l ~/.local/bin/claude

ネイティブ版のmacOS環境(v2.1.287で確認)では、最後の ls -l はバージョン別ディレクトリへのシンボリックリンクを示します。次は出力の例で、実際はリンク元もリンク先も絶対パスで表示されます。

lrwxr-xr-x  1 user  staff  48 Oct  2 10:00 ~/.local/bin/claude -> ~/.local/share/claude/versions/2.1.287

versions/ の下には過去のバージョンも残っています。リンクの行き先がこの形ならネイティブ版です。自分で作ったスクリプトやシンボリックリンクを置いた場合はカスタムランチャーとして扱われ、自動更新はそれを書き換えません。この挙動はv2.1.207から入ったもので、それ以前は更新のたびに独自のリンクへ置き換えられていました。

claude update の出力でも経路を見分けられます。ネイティブやnpmでは最新のときに Claude Code is up to date (<バージョン>) と出ます。Homebrew・WinGet・apkの場合は Claude is up to date! です。

見つかった経路が複数なら、ネイティブの ~/.local/bin/claude だけを残します。npmのグローバル版は npm uninstall -g @anthropic-ai/claude-code、旧ローカルnpm版は rm -rf ~/.claude/local で消します。Homebrewなら brew uninstall --cask claude-code(最新版caskは claude-code@latest)です。

経路を乗り換える順番

設定や会話履歴は ~/.claude 配下に独立して保存されるため、経路を変えても失われません。新しい経路を先に入れ、動作確認してから古い経路を消します。

手順

ネイティブへの乗り換え(npmから)

  1. 1

    新しい経路を先に入れる

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

    新しいバイナリで動作確認する

    claude --version
  3. 3

    確認できてから旧経路を消す

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

順番を逆にすると、新しい経路の導入がネットワーク不調やPATHの不備で失敗したとき、claude が使えない空白期間ができます。インストールしたシェルのPATHは古いままなので、claude が見つからないときは新しいターミナルを開いて試します。

導入済みの経路で入れ直したいときは、claude install --force で強制的に再インストールできます。claude update には upgrade というエイリアスもあります。

claude install --help は、versionにstable・latest・特定のバージョンを指定できると説明しています。

乗り換え後は claude doctor で、意図した経路になっているかを確かめます。v2.1.287の claude doctor --help は「Claude Codeのインストールの健全性を確認する。カレントディレクトリの設定ファイルを信頼確認なしで読む」と説明しています。修復まで行いたい場合は、セッション内の /doctor を使います。

症状から探す

Homebrewが古いバージョンしか入れてくれない

Cask 'claude-code' is unavailable: No Cask with this name exists というエラーが出ます。古いバージョンが入る現象と合わせて、多くは古いcaskインデックスが原因です。

brew update
brew install --cask claude-code

Cask 'claude-code@latest' is not installed と出る

2つのcaskのうち、入れていない側の名前で brew upgrade --cask claude-code@latest を実行すると、Error: Cask 'claude-code@latest' is not installed. になります。まず入っているcaskを調べます。

brew list --cask | grep claude-code

表示された名前で brew upgrade を実行します。何も表示されなければ、どちらのcaskも入っていません。

npmで native binary not installed と出る

v2.1.287の時点でエラー本文は次の内容です。postinstallが実行されていないか、プラットフォーム別のoptional dependencyが取得されていないことを示します。

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

--ignore-scripts や --omit=optional を外して入れ直します。.npmrc の optional=false も原因になります。社内npmミラーを使っているなら、@anthropic-ai/claude-code-darwin-arm64 をはじめとする8種類のプラットフォームパッケージ(darwin-arm64・darwin-x64・linux-x64・linux-arm64・linux-x64-musl・linux-arm64-musl・win32-x64・win32-arm64)が揃っているかも確認します。

postinstallが走るまで、claude はエラーを出すだけのプレースホルダーのスクリプトです。上の2つのどちらかが起きると、そのまま残ります。

Windowsでは bin/claude.exe がこのプレースホルダーのため、メッセージは出ません。PowerShellやCMDが「実行できない」と答えます。

npmの上書きで ENOTEMPTY が出る

npm install -g @anthropic-ai/claude-code を既存の環境へ重ねると、npmが旧パッケージのディレクトリを退避できずに失敗することがあります。エラーの npm error path が示すディレクトリと、隣にある .claude-code-* の残骸を削除して再実行します。

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

nvmでNodeのバージョンを切り替えた場合、npm root -g の配下とエラーが示す場所が一致しないことがあります。その場合はエラーが示したディレクトリを消します。

sudo npm install -g で権限エラーが出た

sudo を付けて回避しないでください。権限やセキュリティ上の問題の原因になります。ネイティブインストーラーに切り替えるか、npmのグローバルディレクトリを書き込める場所に変えます。書き込めない状態で自動更新できないときは、起動時に一度だけ通知が出て、claude doctor に対処の候補が表示されます。

Windowsでnpmのスクリプトが実行できない

running scripts is disabled on this system というエラーは、npmが作る .ps1 ランチャーをPowerShellの実行ポリシーがブロックしているために出ます。この制限はスクリプトファイルだけに掛かるため、irm https://claude.ai/install.ps1 | iex のインストーラーは影響を受けません。npmを使い続けるなら、次のどちらかで回避できます。

  • Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser を実行して、ローカルで作られたスクリプトを許可する
  • npm.cmd と claude.cmd のランチャーを呼ぶ

claude update や claude doctor が固まる

v2.1.214より前では、~/.zshrc などシェル設定のパスがファイルでなくディレクトリになっていると、この2つのコマンドが応答しなくなりました。claude update は Checking for updates と出た直後で止まります。次のコマンドで先頭が d のパスを探し、退避するかv2.1.214以降に更新します。

ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

ZDOTDIR を設定している場合は、$ZDOTDIR/.zshrc も調べます。更新コマンド自体が固まる場合は、インストールスクリプトを再実行して更新します。

Homebrewのディスク使用量が増え続ける

Homebrewはアップグレード後も旧バージョンをディスクに残します。brew cleanup で解放できます。

WinGetとLinuxのパッケージマネージャー

WindowsのWinGetは winget install Anthropic.ClaudeCode で入れ、winget upgrade Anthropic.ClaudeCode で更新します。Linuxのapt・dnf・apkは、署名付きのリポジトリを登録する形です。各リポジトリには stable(約1週間遅れ)と latest の2チャネルがあり、更新はOSの通常のシステム更新に乗ります。Claude Code自身は更新しません。

使い分けの目安

利用形態向く経路理由
個人開発・初めての導入向く経路ネイティブインストーラー理由前提条件がなく、自動更新が既定で効く
brewで開発ツールを管理向く経路Homebrew(CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 を併用)理由一元管理しつつ更新の手間を省ける
既存のNode.js運用に統合向く経路npm理由既存のパッケージ管理にそのまま乗る
組織でバージョンを管理向く経路ネイティブ+managed settings理由requiredMinimumVersion と requiredMaximumVersion でバージョン範囲を強制できる

組織向けの2つの設定は、範囲外のバージョンではClaude Codeが起動を拒否し、許可されたバージョンへ誘導します。一方、通常の設定の minimumVersion は更新の下限を決めるだけで、起動は止めません。この下限があるため、autoUpdatesChannel を stable に切り替えても、すでに入っている新しい版より古いバージョンへは更新されません。

よくある質問

VS Code拡張機能を使うなら、先にCLIを入れる必要がありますか

拡張機能が同梱するCLIはチャットパネル専用の非公開コピーで、PATHには追加されません。拡張機能だけを入れた環境には ~/.local/bin/claude が存在しないため、統合ターミナルで claude を使うなら、ここまでのいずれかの経路でCLIを別途入れます。詳しくはVS Code拡張機能の使い方で扱っています。

迷うのはHomebrewを選ぶときだけで、決めるのはcask名と自動更新の変数の2点です。経路が複数見つかったときは、残す1つを決めて旧経路を最後に消します。Claude Codeのインストール時のエラー全般はClaude Codeインストールエラーの切り分けチェックリストで扱っています。caskの更新中にバックグラウンドセッションが落ちる症状はHomebrewアップグレード後の対処にあります。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/ja/setup
  2. code.claude.com/docs/ja/troubleshoot-install
  3. code.claude.com/docs/ja/vs-code
  4. code.claude.com/docs/en/env-vars
  5. code.claude.com/docs/en/changelog
この記事を共有:XはてブLinkedIn