在 macOS 上使用 Python 時，經常會遇到多版本衝突的問題，比如 python 和 python3 指向不同的路徑，pip 和 pip3 使用不同的 Python 版本等等。這篇文章記錄了我遇到的問題及解決過程，方便日後查閱。

問題背景

以下是本機環境狀況：

❯ python3 -V
Python 3.11.6

❯ python -V
zsh: command not found: python

❯ which python3
/usr/local/bin/python3

❯ which python
python not found

❯ which pip3
/usr/local/bin/pip3

❯ which pip
/opt/homebrew/bin/pip

❯ pip3 --version
pip 23.2.1 from /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/pip (python 3.11)

❯ pip --version
pip 24.2 from /opt/homebrew/lib/python3.10/site-packages/pip (python 3.10)

❯ brew info python
==> [email protected]: stable 3.13.1 (bottled)
Installed
/opt/homebrew/Cellar/[email protected]/3.13.1

遇到的問題

  1. python 無法執行，系統找不到指令。
  2. pip 和 pip3 分別指向不同版本的 Python。
  3. Homebrew 已安裝 Python 3.13，但未作為默認版本。

解決方案

1. 確保 Python 和 pip 的一致性

(1) 查看 pip 和 pip3 路徑

執行以下指令檢查 pip 和 pip3 所指向的 Python 版本：

which pip
which pip3

(2) 使用 Homebrew 統一版本

移除舊的 Python 版本並重新鏈接 Homebrew 的 Python 3.13：

brew unlink [email protected]  # 移除舊版本的鏈接
brew unlink [email protected]
brew link [email protected] --overwrite --force  # 確保 Python 3.13 成為默認版本

重新設置 PATH，確保 Homebrew 提供的 Python 和 pip 在優先路徑中：

echo 'export PATH="/opt/homebrew/opt/[email protected]/libexec/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. 驗證環境

確認 python 和 pip 是否正確：

python -V       # 應為 Python 3.13.x
python3 -V      # 應為 Python 3.13.x
pip --version   # 應指向與 Python 3.13 一致的版本
pip3 --version

3. 處理舊版本依賴

檢查是否有其他軟件依賴於這些舊版本：

brew uses --installed [email protected]
brew uses --installed [email protected]

如果有依賴，升級或重新安裝：

brew upgrade <依賴包>

刪除舊版本：

brew uninstall [email protected]
brew uninstall [email protected]
brew autoremove  # 移除不再需要的依賴

注意事項

  1. 如果不確定是否需要舊版本的 Python，可以保留，但調整 PATH 指向最新版本。
  2. 每次調整後，執行 brew doctor 確保 Homebrew 狀態正常。

結語

通過以上步驟，成功統一了 macOS 上的 Python 環境，並解決了多版本衝突的問題。如果你在配置 Python 環境時遇到類似問題，希望這篇文章能對你有所幫助！