brew install したのにコマンドが使えない（keg-only でリンクされない）

要約

brew install は成功したのにコマンドが見つからない、あるいは古いバージョンが呼ばれる場合、その formula は keg-only である可能性が高い。

keg-only とは、Cellar にはインストールされるが既定の prefix へリンクされない状態を指す。
多くのツールはそこを見に行かないため、入れたのに使えないように見える。brew info <formula> が理由と PATH の通し方を教えてくれる。

よくある原因

1. keg-only 指定: macOS 標準のソフトウェアを覆い隠すことを避けるため、意図的にリンクされていない。
2. PATH の優先順位: /usr/bin の標準版が先に見つかり、Homebrew 版まで到達していない。
3. 案内の未反映: brew info が出す PATH の追記を実行していない。
4. link 未実行・失敗: brew link していない、または既存ファイルと衝突して失敗している。

解決策

1. keg-only かどうかを確認する

brew info <formula>

keg-only の場合は理由と、PATH に含めるための具体的な設定が表示される（公式 FAQ（新しいタブで開く）↗）。

2. 案内された PATH 設定を反映する

echo 'export PATH="/opt/homebrew/opt/<formula>/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

<formula> と prefix は brew info の出力に合わせる。

3. どの実体が呼ばれているか確認する

which -a <command>

複数行が出る場合、上に出た方が実際に実行される。
想定と違うなら PATH の順序を調整する。

4. 必要ならリンクする

brew link <formula>

システム標準のソフトウェアを覆い隠す副作用があるため、影響を理解したうえで使う。
衝突する場合はリンクせず、PATH の順序で切り替える方が安全である。