できない.dev

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

brew install したコマンドが使えないときは、brew info の PATH 設定を反映するか brew link --force すれば直る。
keg-only の formula は既定の prefix にリンクされないためである。

公開: 更新:

症状できない · exit 1
which -a cjpeg

2026-10-17 に homebrew/brew（Homebrew 4.6.20） で実際に打って取った出力。検証環境の詳細

要約

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

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

実行例

Linux 版 Homebrew のコンテナで keg-only の jpeg を入れると、jpeg-turbo と衝突するため Cellar に置かれただけで which -a cjpeg は何も返さず、--force なしの brew link も警告を出すだけでリンクしなかった。brew info が案内する opt/jpeg/bin を PATH の先頭に足すか、brew link --force でリンクすると、cjpeg が見つかるようになる。

$ brew install jpeg
==> Fetching downloads for: jpeg
==> Downloading https://ghcr.io/v2/homebrew/core/jpeg/manifests/10
==> Fetching jpeg
==> Downloading https://ghcr.io/v2/homebrew/core/jpeg/blobs/sha256:32588e95a61f3c5d96dcf9b07c444dad100e0ef26df995d74c4cd93d5e119575
==> Pouring jpeg--10.x86_64_linux.bottle.tar.gz
==> Caveats
jpeg is keg-only, which means it was not symlinked into /home/linuxbrew/.linuxbrew,
because it conflicts with `jpeg-turbo`.
 
If you need to have jpeg first in your PATH, run:
  echo 'export PATH="/home/linuxbrew/.linuxbrew/opt/jpeg/bin:$PATH"' >> ~/.profile
 
For compilers to find jpeg you may need to set:
  export LDFLAGS="-L/home/linuxbrew/.linuxbrew/opt/jpeg/lib"
  export CPPFLAGS="-I/home/linuxbrew/.linuxbrew/opt/jpeg/include"
==> Summary
🍺  /home/linuxbrew/.linuxbrew/Cellar/jpeg/10: 23 files, 991.2KB
==> Running `brew cleanup jpeg`...
$ which -a cjpeg
$ echo $?
1
$ brew info jpeg
==> jpeg: stable 10 (bottled) [keg-only]
Image manipulation library
https://www.ijg.org/
Installed
/home/linuxbrew/.linuxbrew/Cellar/jpeg/10 (23 files, 991.2KB)
  Poured from bottle using the formulae.brew.sh API on 2026-10-17 at 03:18:45
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/j/jpeg.rb
License: IJG
==> Caveats
jpeg is keg-only, which means it was not symlinked into /home/linuxbrew/.linuxbrew,
because it conflicts with `jpeg-turbo`.
 
If you need to have jpeg first in your PATH, run:
  echo 'export PATH="/home/linuxbrew/.linuxbrew/opt/jpeg/bin:$PATH"' >> ~/.profile
 
For compilers to find jpeg you may need to set:
  export LDFLAGS="-L/home/linuxbrew/.linuxbrew/opt/jpeg/lib"
  export CPPFLAGS="-I/home/linuxbrew/.linuxbrew/opt/jpeg/include"
$ brew link jpeg
Warning: jpeg is keg-only and must be linked with `--force`.
 
If you need to have this software first in your PATH instead consider running:
  echo 'export PATH="/home/linuxbrew/.linuxbrew/opt/jpeg/bin:$PATH"' >> ~/.profile
$ which -a cjpeg
$ echo $?
1
$ export PATH="/home/linuxbrew/.linuxbrew/opt/jpeg/bin:$PATH"
$ which -a cjpeg
/home/linuxbrew/.linuxbrew/opt/jpeg/bin/cjpeg
$ brew link --force jpeg
Linking /home/linuxbrew/.linuxbrew/Cellar/jpeg/10... 19 symlinks created.
 
If you need to have this software first in your PATH instead consider running:
  echo 'export PATH="/home/linuxbrew/.linuxbrew/opt/jpeg/bin:$PATH"' >> ~/.profile
$ which -a cjpeg
/home/linuxbrew/.linuxbrew/opt/jpeg/bin/cjpeg
/home/linuxbrew/.linuxbrew/bin/cjpeg

— 2026-10-17 時点の出力

検証環境Git 2.51.2 / Homebrew 4.6.20 / 2026-10-17 検証
検証日
実行環境
homebrew/brew Ubuntu 22.04.5 LTS
バージョン
  • Git 2.51.2
  • Homebrew 4.6.20

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

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 --force <formula>

keg-only の formula は、--force を付けないと「keg-only なので --force を付けてリンクする必要がある」という警告を出してリンクしない（node@20 のような旧バージョン用の formula だけは --force なしでリンクできる）。
また prefix が /usr/local（Intel Mac の既定）のときは、macOS が提供する・覆い隠すことになるソフトウェアは --force を付けても Refusing to link macOS provided/shadowed software と表示されてリンクされない。
その場合は手順 2 の PATH 設定で切り替える（brew(1)（新しいタブで開く） の link の --force と、link.rb の実装（新しいタブで開く））。

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

よくある原因

  1. keg-only 指定: macOS 標準のソフトウェアを覆い隠すことや、他の formula との衝突（例: jpeg は jpeg-turbo と衝突する）を避けるため、意図的にリンクされていない。
    旧バージョン用の formula（node@20 など）も keg-only になる（keg_only_reason.rb（新しいタブで開く））。
  2. PATH の優先順位: /usr/bin の標準版が先に見つかり、Homebrew 版まで到達していない。
  3. 案内の未反映: brew info が出す PATH の追記を実行していない。
  4. link 未実行・失敗: brew link していない、--force を付けずに実行して拒否された、または既存ファイルと衝突して失敗している。
#homebrew #keg-only #brew-link #path #install

この手順で直った？