pyenv 是轻量可靠的 Python 版本管理工具，通过隔离安装与动态 shim 代理实现多版本共存；支持全局、本地、会话级切换，并可配合 pyenv-virtualenv 实现解释器与包双重隔离。
用 pyenv 管理 Python 版本，是解决多项目依赖不同 Python 版本问题最轻量、最可靠的方式之一。它不依赖系统包管理器，也不修改全局 Python，所有版本隔离安装、按需切换，适合开发、测试和 CI 场景。
安装 pyenv（macOS / Linux）
推荐使用 pyenv-installer 脚本一键安装：
- 运行
curl https://pyenv.run | bash，按提示将三行环境变量添加到~/.zshrc（macOS Catalina+）或~/.bashrc（Linux）中，例如：
export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)"
执行 source ~/.zshrc 生效后，运行 pyenv --version 验证。
安装与切换 Python 版本
pyenv 默认只提供版本列表，不预装任何 Python。安装前可先查看可用版本：
立即学习“Python免费学习笔记（深入）”；
-
pyenv install --list | grep "3\.1[0-2]"（筛选主流 3.10–3.12） - 安装指定版本，如：
pyenv install 3.11.9（自动下载、编译、安装到~/.pyenv/versions/3.11.9） - 设为全局默认：
pyenv global 3.11.9 - 在当前目录生效（写入 .python-version）：
pyenv local 3.10.12 - 仅本次 shell 会话生效：
pyenv shell 3.9.18
每次切换后，python --version 和 which python 会立即反映变化，底层通过 shims 动态代理实现，无冲突。
配合虚拟环境（推荐 pyenv-virtualenv）
pyenv 本身不管理 pip 包，建议搭配插件 pyenv-virtualenv 使用：
- 启用插件：在
~/.zshrc中追加eval "$(pyenv virtualenv-init -)"，再source - 创建虚拟环境：
pyenv virtualenv 3.11.9 myproject-env - 激活：
pyenv activate myproject-env（退出用pyenv deactivate） - 也可用
pyenv local myproject-env实现进入目录自动激活
这样既隔离 Python 解释器，又隔离第三方包，真正实现“一项目一环境”。
常见问题处理
安装失败？多数因缺少编译依赖：
- macOS：确保已装 Xcode Command Line Tools（
xcode-select --install） - Ubuntu/Debian：
sudo apt update && sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev - 遇到 SSL 错误？临时设置：
export PYTHON_CONFIGURE_OPTS="--enable-framework"（macOS）或升级 OpenSSL - 想清理旧版本？
pyenv uninstall 3.8.10即可，不残留文件
不复杂但容易忽略：每次安装新版本后，记得用 pyenv rehash 更新 shim 符号链接（通常自动触发，手动执行更稳妥）。
