pyenv 是通过修改 $PATH 优先级在 Shell 层级管理多 Python 版本的轻量可靠方案，支持全局、局部和会话级切换，并可集成 pyenv-virtualenv 创建隔离环境。

用 pyenv 管理多个 Python 版本，是开发中避免环境冲突最轻量、最可靠的方式之一。它不依赖虚拟环境，而是通过修改 $PATH 优先级，在 Shell 层级切换全局、局部或当前会话的 Python 解释器版本。

安装 pyenv（推荐使用 pyenv-installer）

macOS 和 Linux 用户建议用官方安装脚本：

• 运行：curl https://pyenv.run | bash
• 将三段环境变量添加到 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）中，包括 PYENV_ROOT、PATH 扩展和 pyenv init 的 eval 命令
• 执行 source ~/.zshrc（或对应配置文件）使配置生效
• 验证：运行 pyenv --version 和 pyenv versions（应显示 system）

安装与切换 Python 版本

pyenv 默认只管理“已安装”的版本，安装过程自动编译，需提前装好系统依赖（如 macOS 的 Xcode Command Line Tools，Ubuntu 的 build-essential zlib1g-dev libffi-dev libssl-dev）：

• 查看可安装版本：pyenv install --list | grep "^\s*[0-9]" | tail -10
• 安装指定版本（例如 3.11.9）：pyenv install 3.11.9
• 设为全局默认：pyenv global 3.11.9
• 设为当前目录局部版本（会生成 .python-version 文件）：pyenv local 3.9.18
• 仅对当前 Shell 会话生效：pyenv shell 3.8.18

配合 virtualenv 使用更安全

pyenv 本身不创建虚拟环境，但可无缝集成 pyenv-virtualenv 插件：

立即学习“Python免费学习笔记（深入）”；

• 安装插件：git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
• 在 shell 配置中追加：eval "$(pyenv virtualenv-init -)"，然后重新加载
• 创建虚拟环境：pyenv virtualenv 3.11.9 myproject-env
• 激活：pyenv activate myproject-env（退出用 pyenv deactivate）
• 也可用 pyenv local myproject-env 实现进入目录自动激活

常见问题与提示

切换后 python --version 不变？大概率是 shell 缓存了命令路径，执行 hash -d python 清除即可；若仍无效，检查是否被 conda 或其他工具干扰（建议卸载 conda 或将其初始化注释掉）。

某些旧版本（如 2.7.18）编译失败？尝试先设置环境变量：export PYTHON_CONFIGURE_OPTS="--enable-framework"（macOS）或安装缺失的 dev 包（Linux）。

想快速回退到系统 Python？用 pyenv global system 即可，无需卸载任何版本。