---
# System prepended metadata

title: 在 Mac 上使用 pyenv 管理多版本 Python

---

# 在 Mac 上使用 pyenv 管理多版本 Python

在開發不同專案時，常常會遇到 **Python 版本不相容** 的問題。例如某些專案需要 Python 3.11，但另一個專案卻只能在 3.9 上跑。這時候，使用 **pyenv** 就能輕鬆在同一台電腦上管理多個 Python 版本，並自由切換。

---

## 1. 安裝 pyenv

使用 Homebrew 安裝：

```bash
brew install pyenv
```

安裝完成後，確認 pyenv 可用：

```bash
pyenv --version
```

---

## 2. 設定環境變數

為了讓 shell 可以找到 pyenv，我們需要在 `~/.zshrc`（Mac 預設 shell 是 zsh）裡加入設定：

```bash
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
```

讓設定生效：

```bash
source ~/.zshrc
```

確認 pyenv 的 shim 機制已經接管：

```bash
which python
# 應該顯示 /Users/你的帳號/.pyenv/shims/python
```

---

## 3. 安裝指定 Python 版本

例如要安裝 **Python 3.11.9**：

```bash
pyenv install 3.11.9
```

> 如果安裝時出現「缺少 lzma」之類錯誤，請先安裝必要套件：
>
> ```bash
> brew install xz
> ```

---

## 4. 切換 Python 版本

pyenv 提供三種切換方式：

### (1) 全域設定（整台電腦）

```bash
pyenv global 3.11.9
```

### (2) 專案設定（當前資料夾）

```bash
cd ~/Documents/GitHub/llm_engineering
pyenv local 3.11.9
```

這會在專案目錄下生成一個 `.python-version` 檔，讓進入該目錄時自動切換。

### (3) 只在當前 session

```bash
pyenv shell 3.11.9
```

離開終端機或開新視窗就會恢復。

---

## 5. 驗證版本

切換後確認 Python 版本：

```bash
python --version
```

應該會顯示：

```
Python 3.11.9
```

---

## 6. 與 Anaconda 共存的注意事項

如果你同時有安裝 Anaconda，可能會遇到 `(base)` 環境干擾 pyenv。
建議關閉自動啟動 base：

```bash
conda config --set auto_activate_base false
```

重新開啟終端機後，pyenv 的設定就能正常生效。

---

## 總結

使用 pyenv，可以：

* 在同一台電腦上安裝多個 Python 版本
* 為不同專案設定不同版本
* 避免版本相依問題

👉 推薦日常開發用 **pyenv 管理 Python 版本**，再搭配 `venv` 或 `conda` 建立專案專屬的虛擬環境，讓環境更乾淨。

---