pyenv — 用 shim 把 python 命令拦截后路由到指定版本

是什么

pyenv 是一套让一台机器同时装多个 Python 版本、按目录自动切换的工具。本体是纯 bash 脚本，2013 年 yyuu 从 Ruby 圈的 rbenv 直接 fork 过来改成 Python 版。

日常类比：

你家书架上摆着 Python 3.10、3.11、3.12、2.7 四本同名字典
pyenv 是门口的”小助手”：你喊”查 python”时它先看你站在哪个房间——客厅写着 3.12，就递 3.12；进了一个贴着 3.10 的小屋，就递 3.10
你的手不用动，命令永远叫 python，背后到底是哪本字典由小助手按规则替你选

跑起来一行：

pyenv install 3.12.1     # 下载源码、本地编译，装到 ~/.pyenv/versions/3.12.1
pyenv global 3.12.1      # 设全局默认
cd my-project && pyenv local 3.11.7   # 在这个目录写 .python-version

为什么重要

不理解它，多版本 Python 共存只能靠 python3.10/python3.11 这种带后缀的命令调用，写脚本时硬编码版本号——切机器就崩
不理解它，分不清 pyenv / conda / uv / asdf / mise 这一组工具的边界——它们都说”管 Python 版本”，但机制和野心完全不同（下文展开）
不理解 shim 机制，理解不了为什么 which python 指向 ~/.pyenv/shims/python 而不是真实解释器——这个间接层是整个 pyenv（以及 rbenv、nodenv、asdf）家族的核心发明

核心要点

pyenv 的工作流可以拆成 三件事：

shim 拦截：安装时把 ~/.pyenv/shims 插到 PATH 最前面。每个被管的命令（python、pip、pytest…）都对应一个 shim——本体是约 70 行的 bash 脚本。你运行 python xx.py 时，shell 先撞到 shim。
版本解析：shim 调 pyenv-exec，按固定优先级找版本——PYENV_VERSION 环境变量 → 当前目录 .python-version → 一路向上找父目录的 .python-version → ~/.pyenv/version（全局）。命中第一个就停。
真实解释器接管：解析出”3.11.7”后，exec ~/.pyenv/versions/3.11.7/bin/python "$@"。shim 进程被替换成真 Python，argv 透传，没有额外开销（除了启动那一瞬间的 bash 加载）。

整个过程没有 alias、没有改 shell rc 切版本、没有 source——只是 PATH 上插一层 + 一个文本文件标版本。

shim 内部到底长什么样

打开任意一个 shim 文件就能看穿全部魔法：

$ cat ~/.pyenv/shims/python
#!/usr/bin/env bash
set -e
[ -n "$PYENV_DEBUG" ] && set -x

program="${0##*/}"
if [ "$program" = "python" ]; then
  for arg; do
    case "$arg" in
    -c* | -- ) break ;;
    */* )
      if [ -f "$arg" ]; then
        export PYENV_FILE_ARG="$arg"
        break
      fi
      ;;
    esac
  done
fi

export PYENV_ROOT="/Users/me/.pyenv"
exec "/usr/local/bin/pyenv" exec "$program" "$@"

没有任何黑魔法——就是一个小转发器。这是 pyenv 给计算机科学的一个朴实礼物：复杂功能可以纯靠”加一层间接”实现。

实践案例

案例 1：项目按目录自动切版

cd ~/projects/legacy-app
echo "2.7.18" > .python-version
python --version       # Python 2.7.18

cd ~/projects/new-app
echo "3.12.1" > .python-version
python --version       # Python 3.12.1

.python-version 进 git——同事 clone 下来 cd 进去就是同一版本，零配置。

案例 2：从源码装一个新版本

pyenv install 3.13.0
# 实际发生：
#   1. 从 python.org 下载源码 tar.gz
#   2. 调 python-build 子项目执行 configure + make + make install
#   3. 装到 ~/.pyenv/versions/3.13.0
#   4. rehash 重生成 shims

第 2 步会真编译，5-10 分钟，依赖 openssl/readline/sqlite/zlib。mac 上漏 brew 装这些就报错 _ssl module not found。这也是 uv 选择不走源码、改用预编译二进制的根本原因。

案例 3：一次性切版本（不写文件）

PYENV_VERSION=3.10.13 python script.py
# 等价于
pyenv shell 3.10.13 && python script.py

pyenv shell 只设环境变量，不动磁盘——退出 shell 就还原。适合临时测兼容性。

踩过的坑

PATH 顺序错：eval "$(pyenv init -)" 漏写或写在 rc 文件末尾被后续 export PATH=... 覆盖，shim 不生效，which python 还是 /usr/bin/python。修：pyenv init - 必须放最后，或检查 echo $PATH | tr : '\n' | head -3。
.python-version 漏 commit：本地写了但没 git add，同事 clone 跑同份代码报 python3.12: command not found。修：写完立刻 add，CI 加一步 pyenv version 打印。
mac 编译失败：brew install openssl readline xz tcl-tk 缺一不可；M 系列芯片上 LDFLAGS/CPPFLAGS 还得显式指。pyenv-doctor 插件能跑预检。
shim 启动慢：每次 python 都加载一遍 bash 脚本约 80ms。脚本密集场景（pre-commit、test runner）累计变明显。修：长期切换可改用 uv（无 shim），或 pyenv shell 设环境变量绕开。
pip install 后切版本看不见：pip 装的包属于”当前激活版本”的 site-packages。切到另一版本重装即可，或用 poetry/uv 走 .venv。

适用 vs 不适用场景

适用：

多 Python 版本共存（同时维护 2.7 / 3.8 / 3.12 项目）
团队需要”clone 即同版本”（.python-version 进 git）
不依赖 conda 那套预编译科学栈，只要纯 CPython

不适用：

只装一版 Python：直接 brew/apt 即可
想几秒装好新版本：用 uv（python-build-standalone 预编译二进制）
需要 numpy/scipy/cuda 一条龙：用 conda/mamba（pyenv 不管包，只管解释器）
多语言版本管理（同时管 node、ruby、java）：用 asdf 或 mise（机制和 pyenv 一样是 shim，但跨语言）

学到什么

shim 是 PATH-based 版本切换的标准范式：rbenv → pyenv → nodenv → asdf 同源同构。理解一个就理解全家。
bash 脚本能撑起 39k star 的工具：pyenv 本体不到一万行 bash，证明”用对的胶水语言”比”用最强的语言”重要。
“间接一层”是计算机科学万能解药：不能直接修改系统 python？那就在 PATH 上插一层我能控制的脚本，先来到我这里。
“按目录自动切版本”的本质：不是魔法，是 shim 每次启动都从 cwd 往上找一个文本文件——简单到任何人都能自己实现一遍。

关联

uv —— 同问题域的现代竞品（预编译 + Rust 实现）
asdf —— shim 思路推广到所有语言
poetry —— 上层包/虚拟环境管理，常和 pyenv 搭配
nvm —— Node.js 圈的对应物（同样 shim + 按目录切）

反向链接

nvm —— nvm — 在同一台机器上轻松切换 Node 版本