# 用官方腳本解除安裝 Homebrew，並先匯出清單

> 先用 --dry-run 跑官方解除安裝腳本，匯出 formula 與 cask 清單，再清理 shell PATH 殘留與失敗情形

Published: 2026-08-04 | Updated: 2026-09-25

Homebrew 內建官方解除安裝腳本，行為與說明一致。真正要留意的是範圍：它會卸掉 Homebrew，也會卸掉經它裝上的一切，這兩件事的分量，取決於你為什麼來到這裡。

如果只是想騰出空間，先看看 Homebrew 實際占了多少再決定要不要卸。如果只是某個 formula 出了問題，不必把整套環境一起拆掉。

動手前先記下 `brew leaves` 與 cask 清單，再用 `--dry-run` 跑一遍官方解除安裝腳本，把輸出當成刪除計畫來讀。如果問題只在某一個套件，到這裡就該停下來，改用 `brew uninstall`，或走[更安全的 Homebrew 清理路徑](https://mole.fit/tw/blog/how-to-clean-up-homebrew-mac)。

## 什麼時候不該解除安裝 Homebrew

下面這些情況，先別上「核選項」：

- 只是某一個 formula 或 cask 壞了：用 `brew uninstall <name>`，相依成孤兒後再跑 `brew autoremove`。
- 只是缺空間：`brew cleanup -s` 能清掉舊版本與下載快取，不會刪掉安裝前綴。
- 你還需要來自 Homebrew 的 `git`、`node`、`python`、資料庫服務或命令列工具。解除安裝腳本會連 Cellar 與 Caskroom 一起帶走。
- 你打算明天在同一台 Mac 上重裝同一套工具。先匯出下面的清單，用 `brew cleanup` 清理，保留安裝本身。

真正該解除安裝的時候，是你準備徹底離開 Homebrew、在壞掉的安裝之後遷到乾淨前綴，或清掉一台不再需要那些套件的機器。

## 先認清前綴：Intel、Apple Silicon 與 Rosetta 殘留

Homebrew 的預設前綴取決於晶片：

| Mac | 預設前綴 | `brew` 二進位 |
| --- | --- | --- |
| Apple Silicon | `/opt/homebrew` | `/opt/homebrew/bin/brew` |
| Intel | `/usr/local` | `/usr/local/bin/brew` |

刪任何東西之前，先確認自己真正用的是哪一套：

```
uname -m
brew --prefix
which brew
```

`arm64` 是 Apple Silicon。`x86_64` 是 Intel（或 Rosetta 終端機）。從 Intel 遷過來的 Apple Silicon Mac 上，`/usr/local` 下的舊 Intel Homebrew 可能和 `/opt/homebrew` 並存。官方解除安裝腳本會找目前機器的預設前綴；在 `arm64` 上也會考慮 `/usr/local`，以免漏掉殘留的 Intel 前綴。如果你有意保留兩套前綴，請傳 `--path`，只卸你指定的那一套。

在 Intel 上不要整棵手動刪 `/usr/local`。那個目錄還和其他軟體共用。用官方腳本，它只動 Homebrew 自己的樹。

## 官方解除安裝腳本

Homebrew 的 [FAQ](https://docs.brew.sh/FAQ#how-do-i-uninstall-homebrew) 指向 Homebrew/install 倉庫裡的解除安裝腳本。若 Homebrew 日後改了命令，優先從那一頁複製。目前的一行命令是：

```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"
```

想先讀腳本再跑，可以先下載：

```
curl -O https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh
less uninstall.sh
/bin/bash uninstall.sh --help
```

常用參數：

- `--dry-run`（也可寫 `-n`）：只列印將刪除的內容，不做改動。在你在意的機器上，第一次呼叫就該從這裡開始。
- `--path=PATH`：指定前綴（例如 Apple Silicon 上遺留的 Rosetta 時代 `/usr/local`）。
- `--force`：跳過確認提示（設定了 `NONINTERACTIVE` 時也會隱含啟用）。
- `--skip-cache-and-logs`：不動快取與日誌目錄。

別理舊的 mxcl gist，也別跟那些還在寫 `cd $(brew --prefix)` 再用 `git ls-files` 刪檔案的教學。那套流程面向早期 `/usr/local` 佈局，在現在的安裝上不安全。

## 腳本實際會刪掉什麼

解除安裝程式會移除 Homebrew 安裝前綴及其下的目錄：`bin`、`etc`、`include`、`lib`、`opt`、`sbin`、`share`、`var`、`Frameworks`，以及 `Cellar` 與 `Caskroom`。

後兩者才是關鍵。Cellar 裡是每個 formula 的檔案，Caskroom 裡是 cask 中繼資料。卸掉 Homebrew 等於一併卸掉它們，經它裝上的命令列工具會同時消失。

它還會清理 `~/Library/Caches/Homebrew` 與 `~/Library/Logs/Homebrew`、系統級 Homebrew 快取、`/etc/paths.d/homebrew`，以及 `/Applications` 與 `~/Applications` 裡由 Homebrew 管理的 App。

<figure class="blog-diagram">
  <img src="https://mole.fit/img/blog/homebrew-uninstall-scope.webp" width="1360" height="454" loading="lazy" alt="解除安裝腳本會移除含 Cellar 與 Caskroom 的 Homebrew 前綴，以及快取與日誌；套件自己寫入的設定與 shell 設定行會留下。">
  <figcaption>腳本帶走的是套件，不只是套件管理器。留下的是那些套件寫過的設定，以及你自己加進 shell 設定的行。</figcaption>
</figure>

## 動手前先記下已裝了什麼

解除安裝前先用這兩條命令匯出清單：

```
brew leaves > ~/Desktop/brew-formulae.txt
brew list --cask > ~/Desktop/brew-casks.txt
```

`brew leaves` 列出沒有被其他已裝 formula 或 cask 相依的 formula。它是有用的起點，但不是你曾經明確安裝過的完整紀錄。拿去重建環境前，先通讀這兩個檔案。

套件資料和套件檔案要分開看。家目錄裡的設定可能還在，但 `/opt/homebrew/var` 或 `/usr/local/var` 下的 Postgres 資料庫仍在 Homebrew 前綴裡。解除安裝腳本會刪掉 `var`，那裡的資料可能一起走。需要留下的資料，先備份到前綴之外。若在用服務，先停掉：

```
brew services list
brew services stop --all
```

## 可選：先卸 formulae 和 casks

如果你想分階段拆，而不是一次核刪，可以在 `brew` 還能用時先卸套件：

```
brew list --formula
brew uninstall --force $(brew list --formula)
brew list --cask
brew uninstall --cask --force $(brew list --cask)
brew autoremove
brew cleanup -s
```

這樣會清空 Cellar 與 Caskroom，但保留 Homebrew 安裝本身。適合你還不確定 `var` 下有沒有要留的資料，或只想騰出套件占用、稍後用更小的工具集繼續留著 `brew`。真正告別 Homebrew 時，仍要跑官方解除安裝腳本，把前綴、tap 與快取一併清乾淨。

## 執行解除安裝

1. 先帶 `--dry-run` 跑一遍，逐條核對路徑。
2. 去掉 `--dry-run` 再跑，提示時輸入 `y`；若受保護目錄需要 `sudo`，再輸入 macOS 密碼。
3. 終端機若印出 “possible Homebrew files were not deleted” 一類清單，關掉視窗前先複製下來。

下載腳本後的預覽範例：

```
/bin/bash uninstall.sh --dry-run
```

若用遠端一行命令，也建議先下載再傳參數，避免引號套引號，然後執行 `/bin/bash uninstall.sh`。

## 殘留檔案核對清單

腳本結束時可能提示：部分可能屬於 Homebrew 的檔案未能刪除，建議你自行處理，並附上路徑清單。

這些路徑通常只在這裡出現一次。常見原因是 Homebrew 自己沒建立過的目錄權限不對，清單一般不長。關掉終端機前先另存一份，因為在已經卸乾淨的安裝上重跑解除安裝腳本，不會再打出這份清單。

典型殘留會落在你剛卸掉的前綴下：

- Apple Silicon：`/opt/homebrew/etc`、`share`、`var`、`Frameworks` 以及類似空目錄或權限殘缺的目錄
- Intel：`/usr/local` 下同名目錄，但絕不要憑猜測刪掉無關的 `/usr/local` 樹

若腳本點名了路徑，且你確認它只屬於 Homebrew，再明確刪除（`-rf` 後面要有空格）：

```
sudo rm -rf /opt/homebrew/share
```

然後核對：

```
ls /opt/homebrew
ls /usr/local/Homebrew
ls ~/Library/Caches/Homebrew
ls ~/Library/Logs/Homebrew
```

這些位置消失後，預期會看到 “No such file or directory”。如果腳本已經跑完，而 `/opt/homebrew` 或某棵純 Homebrew 樹還在，通常再用 `sudo rm -rf` 刪那個路徑。按 Return 前再確認一遍路徑。

前綴之外的套件設定常常會故意留下：`~/.gitconfig`、語言版本管理器、`~/Library` 下的 App 支援目錄，以及你已經挪出 `var` 的資料庫。那些不屬於 Homebrew 前綴。只有在你清楚歸屬時再刪。

## Shell 設定裡還在提它

解除安裝腳本不會改 `.zprofile`、`.zshrc`、`.zshenv`、`.zlogin` 或 `.bash_profile`。Homebrew 安裝器常會寫入類似這樣的行：

```
eval "$(/opt/homebrew/bin/brew shellenv)"
```

Intel Mac 的預設 PATH 已經包含 `/usr/local/bin`，很多安裝根本不需要這行。Apple Silicon 上則需要它才能找到 `brew`；解除安裝之後，每個新開的 shell 都會去跑一個已經不存在的二進位。

搜尋並刪掉 `brew shellenv`（以及你不再需要、自己加過的 `/opt/homebrew/bin` 或 `/usr/local/bin` PATH 匯出）：

```
grep -n "brew shellenv\|/opt/homebrew\|/usr/local/bin" ~/.zprofile ~/.zshrc ~/.zshenv ~/.zlogin ~/.bash_profile ~/.bashrc 2>/dev/null
```

然後開一個新的終端機分頁。若警告消失，且 `which brew` 沒有任何輸出，PATH 就清理完了。只有打算立刻重裝時，才保留那一行。

## 常見失敗情形

**殘留路徑權限被拒絕。** 腳本列出了路徑卻刪不掉。對每個點名的路徑用 `sudo rm -rf`，`-rf` 和路徑之間要有空格。寫成 `rm -rf/opt/...` 會報 `illegal option`，因為路徑被當成了參數。

**卸到一半 / 提示 “Homebrew is already installed”。** 上一次嘗試留下了 `.git`、`Cellar` 或 `bin/brew`。用正確的 `--path` 再跑官方解除安裝腳本，或按腳本報告清掉殘留前綴；若還想用 Homebrew，再按官方安裝文件重裝。

**清理做到一半後出現 `brew: command not found`。** 要麼解除安裝已經完成、PATH 仍指向舊前綴（修 shell 那一行），要麼 `brew` 沒了但套件還在。別去追經典 gist。前綴目錄還在的話，用官方腳本加 `--path`。

**Apple Silicon 上卸錯前綴。** 你卸掉了 `/opt/homebrew`，但 Rosetta 時代的工具還在 `/usr/local`。確認那棵樹確屬 Homebrew、不是和其他軟體混在一起之後，再以 `--path=/usr/local` 跑腳本。

**服務與登入項目還在呼叫已消失的二進位。** 能停的話，解除安裝前先停 `brew services`。之後檢查「登入項目」以及仍引用 `/opt/homebrew` 或 `/usr/local/Cellar` 的 LaunchAgents。

**舊部落格文章與 2011 年的 gist。** 靠 `git ls-files` 和 `pbcopy` 刪除的指南屬於更早的 Homebrew 佈局。只認 `https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh`。

## 要不要先做更小的清理

更小的清理：`brew cleanup` 清舊版本與下載快取，`brew uninstall <formula>` 卸單一套件，`brew autoremove` 清掉不再需要的相依。在 [Mole 的「分析」檢視](https://mole.fit/tw/mac-disk-analyzer) 裡，清理前先掃一遍 Homebrew 目錄，清理後再掃一次，對比體積變化。Mole 不會自動追蹤這些命令帶來的變化。

## 用匯出的清單重建

新機器裝好 Homebrew 之後，兩條命令就能裝回原來的內容：

```
xargs brew install < brew-formulae.txt
xargs brew install --cask < brew-casks.txt
```

必須分開跑，因為 cask 需要 `--cask`，混在一起會有一半失敗。

`brew list` 會帶上相依，整份重放會把那些相依也標成明確安裝，之後 `brew autoremove` 能刪掉的東西就變了。`brew leaves` 能避開不少這種情況，但它也不等於「你當初點過名的安裝歷史」：你主動裝過的東西，也可能同時被別的套件相依。重裝前通讀清單，把還需要的工具補進去。

## 常見問題

### 解除安裝 Homebrew 會刪掉它裝過的全部套件嗎？

還在 Cellar 與 Caskroom 裡的會。官方腳本會移除前綴，formula 與 cask 中繼資料一起走。前綴之外的設定與資料可能留下。

### `/opt/homebrew` 和 `/usr/local` 有什麼差別？

`/opt/homebrew` 是 Apple Silicon 的預設前綴。`/usr/local` 是 Intel 的預設前綴，遷過來的 Mac 上也可能還裝著舊的 Rosetta Homebrew。刪之前務必先看 `brew --prefix`。

### 跑解除安裝腳本前，要不要先卸掉每個 formula？

只有當你想分階段清理，或需要先檢查 `var` 裡的資料時才有必要。腳本本來就會清掉前綴裡已裝的套件。無論哪種做法，只要可能重裝，都先匯出清單。

### 為什麼解除安裝後還會留下目錄？

權限問題，或 Homebrew 自己沒建立過的目錄，都可能擋住刪除。腳本只會列印一次這些路徑。確認它們是 Homebrew 殘留後，再用 `sudo` 刪。

### 整棵 `/usr/local` 都能刪嗎？

不能。在 Intel Mac 上這個目錄是共用的。用官方解除安裝腳本，若還有殘留，只刪它點名的路徑。

### 每個新終端機都還在報 brew shellenv 錯誤，怎麼辦？

從 zsh 或 bash 的啟動檔裡刪掉 `eval "$(...brew shellenv)"` 那一行，再開一個新分頁。解除安裝腳本不會替你改這些檔案。

---

Canonical HTML page: https://mole.fit/tw/blog/how-to-uninstall-homebrew-mac
Blog index for agents: https://mole.fit/tw/blog/llms.txt
Site index for agents: https://mole.fit/llms.txt