Homebrew 安裝教學｜macOS 套件管理與常見錯誤排解

Homebrew 是 macOS 的套件管理工具，能用 brew 指令安裝、更新與移除軟體，也能透過 Cask 管理圖形化 App。第一次安裝時，除了執行安裝器，還需要依終端機的提示設定 shell 環境；若安裝完成卻出現 brew: command not found，通常應先確認執行檔路徑與 PATH。

文章目錄

Homebrew 是什麼

Homebrew 是社群維護的開源專案，將軟體的下載位置、依賴套件與安裝方式整理成可重複執行的套件定義。Formulae 主要提供命令列工具與函式庫，Casks 則用來安裝圖形化應用程式；Mac 的開發工具與日常 App 因此可以集中管理。

安裝 Homebrew

安裝前需要 Xcode Command Line Tools，或完整的 Xcode。尚未安裝時，可以在終端機執行 xcode-select --install，並依系統視窗完成安裝。macOS 與硬體支援條件會調整，執行前可核對 Homebrew 安裝文件。接著從 Homebrew 官網取得以下安裝指令：

# 安裝 Homebrew
/bin/bash -c \
"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安裝器結束後，先完成畫面上 Next steps 列出的 shell 設定，再執行 brew --version。只看到安裝完成訊息，還不代表目前的 shell 已經找得到 brew。

Apple Silicon 與 Intel 的 PATH 設定

以下範例適用 macOS 預設的 zsh 與 Homebrew 標準安裝路徑。brew shellenv 會輸出環境設定，eval 將設定套用到目前 shell；寫入 ~/.zprofile 則讓之後的新登入 shell 也能取得設定。若安裝器列出的路徑或 shell 不同，以安裝器的 Next steps 為準；已有相同設定就不必重複加入。

Mac 架構	預設 Homebrew 路徑
Apple Silicon	`/opt/homebrew`
Intel	`/usr/local`

Apple Silicon Mac 的標準 zsh 設定：

# 僅初次設定時加入；已有同一行就不用重複執行
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

# 套用到目前的終端機
eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Mac 的標準 zsh 設定：

# 僅初次設定時加入；已有同一行就不用重複執行
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile

# 套用到目前的終端機
eval "$(/usr/local/bin/brew shellenv)"

brew 找不到指令的排查方式

若出現 zsh: command not found: brew，先用符合架構的完整路徑執行 brew --version。完整路徑能執行、單獨輸入 brew 卻不行，表示應檢查 shell 設定與 PATH；完整路徑也不存在，則回頭檢查安裝是否完成或是否使用自訂路徑。套用設定後可用以下指令確認，不需要先重裝所有套件。

# 確認目前 shell 找到的執行檔與安裝位置
command -v brew
brew --prefix
brew --version

Homebrew 基本操作

常用操作可先由下表查找；安裝特定版本或啟動服務前，再確認套件自己的使用說明。

用途	指令
搜尋套件	`brew search 名稱`
安裝套件	`brew install 名稱`
更新套件資訊	`brew update`
升級指定套件	`brew upgrade 名稱`
解除安裝	`brew uninstall 名稱`

安裝套件 (Formulae)

Homebrew 主要用來安裝「命令列工具」或「函式庫」。例如安裝 OpenJDK 可以這樣輸入。

# 安裝最新版 Java
brew install openjdk

# 安裝 Java 17
brew install openjdk@17

# 安裝 Java 21
brew install openjdk@21

# 重新安裝
brew reinstall openjdk

# 一次安裝多個
brew install openjdk gradle

軟體與套件安裝後就可以直接使用，有些要自己另外加入 PATH。以 openjdk@17 為例，安裝後他會出現以下訊息：

echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc

這是因為 openjdk@17 被標註 keg-only，通常是因為同一個軟體有很多版本，Homebrew 會幫使用者安裝與更新，但如果希望輸入 java 就啟動它，需要自己加入 PATH 中，方法是直接複製上面那行 echo ... >> ~/.zshrc 到 Terminal 上按下 Enter。否則就是使用他的完整名稱去啟動它。

如果對絕對路徑、相對路徑不了解，可以參考 Linux 基本概念－絕對位置、相對位置、檔案系統這篇文章，Linux 與 macOS 都屬於類 Unix 系統，路徑概念可以互相對照。

重新查看安裝訊息

安裝成功後會顯示相關的使用說明，如果想要重看一次這個訊息，可以使用 brew info 指令，例如 brew info openjdk 。

使用 link 指令綁定版本

前面提到有些軟體與套件被標注 keg-only，安裝後不能直接在終端機使用名稱來使用它。這時候可以用 brew link 指令，以 MySQL Client 為例：

# 安裝 MySQL Client 端
brew install mysql-client

安裝成功後使用 mysql 會出現 zsh: command not found: mysql，必須使用它的完整路徑 /opt/homebrew/opt/mysql-client/bin/mysql 才能啟動。

除了把路徑加入 PATH，也可以使用 brew link 指令自動連結到 PATH。

# 一般連結，但是對 keg-only 的會失效
brew link mysql-client

# 強制連結，確認過系統中沒有其他 mysql 就可以強制綁定
brew link --force mysql-client

# 連結後就可以直接在終端機使用 mysql-client 了
mysql -h example.com -u root -p

# 解除綁定
brew unlink mysql-client

也可以用這種 link 方式去指定 openjdk@17、openjdk@21 等各種版本，變成終端機輸入 java 時候的預設版本。

安裝圖形化軟體 (Casks)

Cask 則是 Homebrew 的擴充功能，專門用來安裝 macOS GUI 應用程式（例如 Chrome、Visual Studio Code、Slack）。它會自動下載 .dmg / .pkg 檔，並安裝到 /Applications。可以看以下範例。

# 安裝 Chrome
brew install --cask google-chrome

# 安裝 Visual Studio Code
brew install --cask visual-studio-code

這些軟體安裝後就會出現在 Mac 的啟動台，以及 Finder 的應用程式裡面，可以直接啟動。

搜尋套件

可以直接在終端機使用指令搜尋想要的套件，例如搜尋 docker。

# 搜尋 docker
brew search docker

會出現 Formulae 與 Casks 搜尋結果。
也能開啟瀏覽器在 https://brew.sh 直接搜尋。或是直接在 Google 搜尋，例如搜尋 brew chrome 第一個搜尋結果通常就是 https://formulae.brew.sh/cask/google-chrome。

管理已安裝套件

安裝後可以查詢版本、更新指定套件，或先預覽待清除的舊檔案，再決定是否執行清理。

更新套件

除了安裝與刪除之外，Homebrew 也可以更新。

# 更新 Homebrew 本身，並且檢查有什麼軟體更新了
brew update

# 查詢哪些軟體與套件有更新了
brew outdated

# 全部都更新
brew upgrade

# 更新指定軟體，例如 Java 17 雖然不是最新的 Java，但本身還是會有安全更新
brew upgrade openjdk@17

# 也可以一次指定多個需要更新的
brew upgrade openjdk gradle

已安裝清單與解除安裝

可以查看透過 Homebrew 安裝的套件，如果需要解除安裝只要使用 brew uninstall 指令即可。

# 列出已安裝的 Formulae 與 Casks
brew list

# 解除安裝
brew uninstall <套件名稱>

# 解除安裝範例
brew uninstall openjdk
brew uninstall mysql-client
brew uninstall google-chrome

健康檢查

Homebrew 提供 brew doctor 指令，可以幫系統做一次健康檢查，確認 Homebrew 的安裝環境是否正常，會告知有哪些潛在問題需要修正。例如在安裝套件失敗、或是升級 macOS 之後，就可以檢查是否有 PATH 沒設定好、舊套件殘留或權限錯誤。

# 健康檢查
brew doctor

清除舊資料

Homebrew 將 formula 安裝到 Cellar，但安裝、升級或重新安裝後，預設可能自動執行 cleanup，因此不能保證舊版本一直保留或可隨時切回。清理前可用 brew cleanup -n 預覽；下載快取的實際位置則可用 brew --cache 查詢。

# 清除所有套件的舊版本和快取
brew cleanup

# 只清除指定套件的舊版本
brew cleanup <套件名稱>

# 模擬清除（只顯示會刪哪些檔，不實際刪）
brew cleanup -n

# 清除快取，包含仍可用版本的下載檔；這會實際刪除
brew cleanup -s

有時候會出現類似以下訊息：
Warning: Skipping ffmpeg: most recent version 8.0_1 not installed

這是因為範例中的 ffmpeg 還沒更新到最新版，所以舊版不能刪除，使用 brew outdated 就會看到目前安裝的 ffmpeg 版本跟目前的最新版分別是什麼：
ffmpeg (7.1.1_3) < 8.0_1

將範例中的 ffmpeg 更新到可用的新版本後，可再檢查 cleanup 結果。解除安裝時，Homebrew 預設也可能自動移除不再需要的依賴；剩餘項目可用 brew autoremove -n 預覽，再以 brew autoremove 清理。若設定 HOMEBREW_NO_AUTOREMOVE，則會停用這類自動移除行為。

其他常用指令

# 獲得預設路徑
brew --prefix

# 獲得某個套件的路徑
brew --prefix <套件名稱>
brew --prefix python  # 範例

# 查詢有更新的套件
brew outdated

# 自動清除不再被依賴的套件
brew autoremove

系統服務

Homebrew 可以將安裝的套件變成系統服務，未加 sudo 時會註冊為使用者登入後啟動的服務。就像是 Windows 中的服務，或是 Linux 中的 Systemd。

以 Ollama 為例（用來執行大語言模型）安裝完成後，預設需要在終端機手動輸入 ollama serve 才能啟動後台。但如果將它註冊為系統服務，就可以讓它在使用者登入時自動啟動，免去手動操作。

# 啟動服務
brew services start ollama

# 停止服務
brew services stop ollama

# 重啟服務
brew services restart ollama

# 查看目前服務狀態
brew services list

參考來源

Homebrew: Installation (安裝條件與環境設定)

Post Views: 8,164