Homebrewの既定の配置先は、Apple Siliconでは/opt/homebrew、Intel Macでは/usr/localです。HomebrewのFAQに示されるこの違いを手がかりに、まず実行アカウント、Shell、実際のインストール先を確認してください。そのうえで、対象環境にbrew shellenvが読み込まれているかを調べます。

SSHの対話型ターミナルでは動くのにCIやバックグラウンド処理では失敗する場合、Homebrewを入れ直す前に、その処理が使うShellと環境変数を直します。

この記事の対象者
- SSHで遠隔Macに接続し、Homebrewのコマンドが呼び出せず困っている開発者。
- macOSのCIやバックグラウンド処理で、対話型ターミナルと異なる挙動を調査するエンジニア。
- 共有MacのアカウントやShell設定を管理するプラットフォーム担当者。

01

1. 遠隔MacでHomebrewのコマンドが見つからない場合は、失敗箇所を分けます

最初に区別するのは、brew自体が実行できないケースと、Homebrewで導入したソフトウェアのコマンドだけが実行できないケースです。さらに、どちらも特定のCIジョブや自動処理だけで失敗するなら、インストールではなく実行環境の違いを疑います。

たとえば、対話型SSHではbrewが動く一方、ビルドジョブではxcodebuildを含むコマンドが見つからないとします。この場合、管理者のターミナルで成功した結果だけでは、ジョブが使うPATHまで正しいとは確認できません。

まず、失敗したコマンド、実行ユーザー、接続方法、Shell、エラー全文を記録します。次に、成功する入口と失敗する入口で同じ情報を比較します。こうすれば、Homebrewの導入状態とPATHの問題を取り違えにくくなります。

02

2. Apple SiliconとIntelでHomebrewの配置先を確認します

Apple SiliconとIntelでは既定のインストール先が異なります。ただし、既定値は個々のMacの実際の配置先を保証するものではありません。過去の移行やカスタム設定がある場合は、公式資料の例をそのまま当てはめず、対象ホストで確認してください。Homebrewのインストール説明とFAQの前提説明も照合に使えます。

現在のShellで、次のように調べます。

command -v brew
brew --prefix
brew doctor
uname -m

command -v brewが何も返さなければ、現在のPATHからbrewを発見できていません。brew --prefixまで実行できるなら、表示された配置先とuname -mの結果を記録し、実行環境や想定している構成と一致するか確認します。診断コマンドの意味はHomebrewのコマンドマニュアルを参照してください。

brewが見つからない段階では、配置先を推測してPATHへ追加するより、インストールの有無と実際の実行ファイルを調べるのが先です。インストール済みの実行ファイルを見つけたら、現在のShellでbrew shellenvを評価したときにPATHがどう変わるかも確認します。

03

3. SSHでログインするとbrewが見つからない原因を調べます

SSHの対話型セッションで動く設定が、非対話型のリモートコマンドでも読み込まれるとは限りません。どの起動ファイルが使われるかはShellや起動方法で異なるため、zshの起動ファイルについてはzsh公式のファイル読み込み仕様を確認し、別のShellの設定と混同しないでください。

まず、失敗する接続方法そのもので状況を記録します。

printf 'shell=%s\n' "$SHELL"
ps -p $$ -o comm=
printf 'PATH=%s\n' "$PATH"
command -v brew

$SHELLはアカウントに設定されたログインShellを示す場合があります。現在動いているShellの判断材料として、それだけに頼らず、プロセス情報やコマンドの結果も合わせて確認します。次に、確認できたHomebrewの配置先を使い、brew shellenvを現在のShellで評価してPATHとcommand -v brewを再確認してください。

修正する場合は、その接続方法で実際に読み込まれる設定ファイルだけを対象にします。設定を広範囲に書き換える前に、変更前の内容と対象ユーザーを控え、SSHの対話型接続と非対話型コマンドを別々に試します。

04

4. CIや自動処理が使うShellとアカウントを特定します

CI、スケジュール実行、常駐サービスでは、担当者がログインして使うShellとは別のアカウントや起動環境が選ばれることがあります。自動処理のログ、Runnerの設定、サービスの実行情報から、実際のユーザーとShellを特定してください。自前のRunnerを使う場合は、GitHub ActionsのRunner監視・トラブルシューティング資料も確認材料になります。

診断用の一時ステップをジョブに追加し、次の情報をログに出すと、管理者のターミナルではなくジョブ自身の状況を確認できます。

id -un
printf 'shell=%s\n' "$SHELL"
ps -p $$ -o comm=
printf 'PATH=%s\n' "$PATH"
command -v brew

ジョブ内でbrewが見つからないなら、ジョブが使うShellの起動経路に合わせてbrew shellenvを読み込ませます。反対に、brewは動くが特定のツールだけ見つからない場合は、そのツールの配置先とジョブのPATHを調べます。成功したログに実行ユーザー、Shell、PATH、コマンドの場所が残る形で再テストしてください。

05

5. 権限やインストール先に異常がある場合は、変更前に記録します

実行ファイルが存在するのに読み込みや実行ができない場合は、配置先とその親ディレクトリの所有者・権限を調べ、実行ユーザーが想定どおりか確認します。共有Macで複数のアカウントが同じHomebrewの領域を使っている場合も、誰がその領域を管理しているかを先に明確にしてください。

HomebrewのMac管理者向け説明は、Homebrewの管理アカウントと権限の考え方を確認する資料です。原因が分からないまま、再帰的な所有者変更、全体への権限付与、sudoによる強制実行を行うと、別アカウントや自動処理に影響するおそれがあります。

権限を変える前に、対象パス、現在の所有者、実行ユーザー、失敗した操作を記録してください。原因がPATHなのに権限を広げても、Shellがコマンドを見つけられない問題は解決しません。

06

6. 実行環境ごとの再テストで、修正先を決めます

最後に、実際に失敗していた経路で代表的なコマンドを実行します。対話型Shell、SSHコマンド、CIやバックグラウンド処理を別々に検証し、実行ユーザー、Shell、コマンドの場所、終了状態をログに残してください。

次の項目を順に確認すると、修正対象を判断できます。

  • [ ] 対象のSSH接続または自動処理で実行ユーザーを確認した。
  • [ ] 現在のShellと、実行時に使われる起動ファイルを確認した。
  • [ ] brew --prefixで実際のHomebrew配置先を記録した。
  • [ ] brew shellenvの適用後にPATHとcommand -v brewを再確認した。
  • [ ] Homebrewのコマンドと、導入済みツールのコマンドを分けて試した。
  • [ ] 変更後に、もともと失敗していたSSH接続またはジョブで再テストした。
観測結果 優先して直す対象 次の判断
すべての入口でbrewが見つからない 実際の配置先、インストール状態 実行ファイルが存在するか調べます
対話型SSHでは成功し、リモートコマンドでは失敗する Shellの起動ファイル、PATH 失敗する接続方法で再テストします
対話型Shellでは成功し、CIだけ失敗する Runnerの実行ユーザー、Shell、環境変数 ジョブログで修正を検証します
brewは動くが導入済みツールが見つからない ツールの配置先、PATH ツール側の呼び出し経路を確認します
所有者や権限が想定と異なる Homebrewの管理アカウント 証拠を保存してから変更範囲を決めます

問題が一つのCIジョブに限られるなら、まずそのジョブの起動環境を修正します。配置先、アカウント、ノードの基準状態まで信頼できない場合に限り、環境の再構築や実行ノードの変更を検討します。手元のMacを個人ごとに使い回す運用は、所有者への依存や設定差、常時稼働環境の保守負担が残ります。一方、安定したmacOS実行環境を分けて確保する場合も、Shell設定やCIの検証は必要です。まずは遠隔Macの利用案内で利用方法を確認し、自分で機材を保有する場合との違いはMac miniの構成案内と比べてください。ローカルで再現できず、特定期間だけmacOSの確認先が必要なら、VpsMeshの遠隔Macレンタルも選択肢になります。