- Python 的版本問題比 Node 麻煩：系統本身可能依賴某個版本的 Python，隨便升級會弄壞系統工具；不同專案又常常卡在不同版本。
- pyenv 的做法是把各版本裝在使用者目錄下，用 shim 攔截
python指令再轉發到指定版本，不動到系統的 Python。 - 要先分清楚兩件事：pyenv 管的是「用哪一版 Python」，
venv管的是「這個專案裝了哪些套件」。 - 兩者是互補的，不是二選一。
macOS
一、安裝 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
確認安裝路徑存在：
ls /usr/local/bin/brew # Intel Mac
ls /opt/homebrew/bin/brew # Apple Silicon (M1/M2)
兩個路徑不同是重點：Apple Silicon 的 Homebrew 裝在 /opt/homebrew，而不是 Intel 時代的 /usr/local。網路上舊教學給的路徑常常是錯的。
設定 PATH：
nano ~/.zshrc
加入（Apple Silicon）：
export PATH="/opt/homebrew/bin:$PATH"
在 nano 裡按 Ctrl + X，再按 Y 確認存檔。
重新載入設定：
source ~/.zshrc
確認變數正確：
echo $PATH
brew --version
二、安裝 pyenv
brew install pyenv
確認：
pyenv versions
三、初始化 shell
這一步不能跳過。 只裝好 pyenv 但沒設定初始化的話，pyenv install 能用，但 pyenv global 切了版本卻沒有效果——因為 shim 沒有掛進 PATH。
在 ~/.zshrc 加入：
# pyenv
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
最後一行是給 pyenv-virtualenv 外掛用的，沒裝那個外掛可以省略。
重新載入並確認：
source ~/.zshrc
echo $PATH
PATH 的最前面應該要看到 .pyenv/shims。
四、安裝 Python 版本
pyenv install 3.9.6
確認裝好了：
pyenv versions
五、設定要用哪一版
# 全域預設
pyenv global 3.9.6
# 只在目前這個資料夾
pyenv local 3.9.6
pyenv local 會在當前目錄產生一個 .python-version 檔案，之後只要 cd 進這個目錄就自動切換版本。這個檔案建議進版控，效果類似 Node 的 .nvmrc。
Windows
Windows 用的是另一個專案：pyenv-win。
一、確認 pip 可用
開啟 PowerShell 或 cmd，輸入 pip。有出現說明訊息就代表可以用 pip 安裝。
二、安裝
PowerShell：
pip install pyenv-win --target $HOME\.pyenv
cmd：
pip install pyenv-win --target %USERPROFILE%\.pyenv
三、設定環境變數
在 PowerShell 執行：
[System.Environment]::SetEnvironmentVariable('PYENV', $env:USERPROFILE + "\.pyenv\pyenv-win\", "User")
[System.Environment]::SetEnvironmentVariable('PYENV_ROOT', $env:USERPROFILE + "\.pyenv\pyenv-win\", "User")
[System.Environment]::SetEnvironmentVariable('PYENV_HOME', $env:USERPROFILE + "\.pyenv\pyenv-win\", "User")
再把 pyenv 的 bin 與 shims 加進 PATH：
[System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"), "User")
注意 shims 要放在 PATH 的前面，才能攔截到 python 指令。
四、驗證
關閉所有開著的終端機（PowerShell 與 cmd），重新開啟。 環境變數的變更不會套用到已經開著的視窗，這是最容易卡住的一步。
pyenv --version
常用指令
輸入 pyenv 會列出所有可用指令：
| 指令 | 用途 |
|---|---|
pyenv versions | 列出所有已安裝的 Python 版本 |
pyenv version | 顯示目前使用的版本與它的來源 |
pyenv install -l | 列出所有可安裝的版本 |
pyenv install <version> | 安裝指定版本 |
pyenv uninstall <version> | 移除指定版本 |
pyenv global <version> | 設定全域版本 |
pyenv local <version> | 設定當前目錄的版本 |
pyenv shell <version> | 只對目前這個 shell 生效 |
pyenv rehash | 重建 shims |
pyenv which <executable> | 顯示某個執行檔的完整路徑 |
pyenv update | 更新可安裝版本的清單快取 |
查看目前版本
pyenv version
還沒設定過的話會看到提示：
No global/local python version has been set yet. Please set the global/local version by typing:
pyenv global 3.7.4
pyenv local 3.7.4
版本的優先順序
三個層級由高到低：
pyenv shell（環境變數PYENV_VERSION）——只在目前 shell 生效pyenv local（.python-version檔案）——當前目錄與其子目錄pyenv global——其他所有情況
搞不清楚現在為什麼是某個版本時，pyenv version 會直接告訴你它是從哪一層來的。
安裝特定版本
# 正式版
pyenv install 3.9.6
# 預覽版也裝得到
pyenv install 3.10.0b3
什麼時候要 pyenv rehash
如果用 pip 安裝或移除了會產生執行檔的套件（例如 black、pytest、django-admin），或是手動改動了某個版本資料夾的內容，要執行 rehash 通知 pyenv 重建對應的 shim：
pyenv rehash
沒 rehash 的症狀是：套件明明裝好了，但輸入指令卻說找不到。
2026 年後記
本文保留當時 pyenv 與 pyenv-win 的安裝紀錄。Python、Homebrew、pip 與作業系統的安裝方式會更新，實作前請以目前官方文件確認。