Apple Silicon Mac用pyenv管理Python多版本（含镜像加速）

Mac 自带的 /usr/bin/python3 是 Apple 预装的，版本偏旧且不能动（动了会破坏系统工具）。用 pyenv 管理多版本 Python 不碰系统 Python，通过 shim 机制在用户态切换版本。

⚠️ 核心原理：pyenv 把 ~/.pyenv/shims 插到 PATH 最前面。敲 python3 时 shell 先命中 shim，shim 按 PYENV_VERSION → .python-version → global → system 顺序解析版本。shims 没置顶，python3 就会被系统或其他路径截胡——这是最常见的坑。

一、安装编译依赖

pyenv 从源码编译 Python，需先装编译依赖：

xcode-select --install

brew install openssl@3 readline sqlite3 xz zlib tcl-tk@8 pkgconf

不装这些依赖，pyenv install 能成功，但编译出的 Python 会缺 ssl/sqlite/tkinter。

二、安装 pyenv

brew install pyenv

三、配置 ~/.zshrc（关键：shims 置顶）

加入：

# pyenv 多版本 Python 管理（shim 机制，不碰系统 /usr/bin/python3）
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/shims:$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# pyenv 下载 Python 源码走 npmmirror 镜像（国内加速）
export PYTHON_BUILD_MIRROR_URL="https://npmmirror.com/mirrors/python/"

关键点：

1. $PYENV_ROOT/shims 必须放 $PATH 最左边，否则会被 fnm 或其他路径挤下去
2. 去掉 eval "$(pyenv init --path)"——新版 pyenv 单靠 init - + 手动置顶 shims 即可，避免重复加 PATH
3. PYTHON_BUILD_MIRROR_URL 让 Python 源码包从 npmmirror 下载

生效：

source ~/.zshrc
hash -r          # 清除 zsh 命令缓存

四、安装 Python

pyenv install --list | grep -E '^\s*3\.(1[0-9])\.[0-9]+$' | tail -10   # 查看可装版本

pyenv install 3.14   # 安装最新稳定版（截至 2025 年 10 月为 3.14）
pyenv global 3.14    # 设为默认

双版本备用：

pyenv install 3.13
pyenv global 3.14      # 默认 3.14
cd myproject && pyenv local 3.13   # 该项目锁定 3.13

五、验证

which python3        # 应指向 ~/.pyenv/shims/python3
python3 --version
which python         # ~/.pyenv/shims/python
/usr/bin/python3 --version   # 系统原版，未被破坏

# 验证关键模块齐全
python3 -c "import ssl, sqlite3, lzma, readline, tkinter; print('all ok')"

若 tkinter 报错，说明编译时没链到 tcl-tk@8，需在 ~/.zshrc 加编译环境变量后重编：

export LDFLAGS="-L$(brew --prefix openssl@3)/lib -L$(brew --prefix readline)/lib -L$(brew --prefix sqlite3)/lib -L$(brew --prefix zlib)/lib -L$(brew --prefix xz)/lib -L$(brew --prefix tcl-tk@8)/lib"
export CPPFLAGS="-I$(brew --prefix openssl@3)/include -I$(brew --prefix readline)/include -I$(brew --prefix sqlite3)/include -I$(brew --prefix zlib)/include -I$(brew --prefix xz)/include -I$(brew --prefix tcl-tk@8)/include"
export PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig:$(brew --prefix sqlite3)/lib/pkgconfig:$(brew --prefix tcl-tk@8)/lib/pkgconfig"

然后：

pyenv uninstall 3.14
pyenv install 3.14

六、pip 与项目隔离

pyenv 装的 Python 自带 pip。永远用 python3 -m pip 而不是裸 pip，避免切错版本。

标准工作流：

mkdir myproj && cd myproj
pyenv local 3.14          # 锁定项目 Python 版本
python3 -m venv .venv     # 建隔离环境
source .venv/bin/activate
python -m pip install --upgrade pip
pip install requests      # 包装进 .venv，不污染全局
pip freeze > requirements.txt
deactivate

.gitignore 加一行：

.venv/

pip 国内镜像：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 或 npmmirror：https://registry.npmmirror.com/pypi/simple

七、常用命令

pyenv versions          # 已装版本，* 是当前
pyenv version           # 当前版本及设置来源
pyenv install --list    # 可装版本
pyenv install 3.14      # 装指定版本
pyenv global 3.14       # 用户级默认
pyenv local 3.13        # 项目级锁定
pyenv shell 3.13        # 当前 shell 临时切换
pyenv uninstall 3.14    # 卸载
pyenv rehash            # 重建 shim（装/卸版本后）

八、踩坑与排错

坑 1：python command not found，但 python3 是系统的

pyenv version 显示 3.14，python3 --version 却还是系统的——原因是 shims 没进 PATH 最前。检查 pyenv 段是否写成：

export PATH="$PYENV_ROOT/shims:$PYENV_ROOT/bin:$PATH"

并 source ~/.zshrc && hash -r。

坑 2：tcl-tk 版本冲突

装了无后缀 tcl-tk（9.0）时，编译 Python 会静默跳过 _tkinter。必须装 tcl-tk@8 并在 LDFLAGS 里显式指向它。

坑 3：brew 升级 openssl 到 4、tcl-tk 到 9

不用担心。pyenv 编译是"编译期定型"——openssl@3、tcl-tk@8 的 Cellar 目录会一直保留，已编译的 Python 不受影响。只有主动 pyenv uninstall + install 才会重新探测 brew。建议 brew pin openssl@3 tcl-tk@8 锁定版本。

坑 4：pyenv 与 fnm 共存时 PATH 顺序

.zshrc 建议顺序：

# 1. 中科大 Homebrew 源
# 2. eval "$(/opt/homebrew/bin/brew shellenv)"
# 3. fnm 段
# 4. pyenv 段（shims 显式置顶，放最后）

pyenv 段放最后，确保 ~/.pyenv/shims 在 PATH 最前。

九、最终 .zshrc 参考

# pyenv 多版本 Python 管理
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/shims:$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# pyenv 下载 Python 源码走 npmmirror 镜像
export PYTHON_BUILD_MIRROR_URL="https://npmmirror.com/mirrors/python/"

# pip 国内镜像
export PIP_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

未经允许不得转载：编源视界 » Apple Silicon Mac用pyenv管理Python多版本（含镜像加速）