pyenv 是一个无需 root 权限、不依赖系统包管理器的 python 版本管理工具，通过修改 path 和 pythonpath 实现按需切换解释器版本，专注解决“用哪个 python 执行脚本”问题。
什么是 pyenv
pyenv 是一个用于管理多个 Python 版本的命令行工具。它不依赖系统包管理器，也不需要 root 权限，通过修改 PYTHONPATH 和 shell 的 PATH 环境变量，让终端能按需切换不同版本的 Python 解释器。它本身不管理虚拟环境（那是 pyenv-virtualenv 插件的事），专注解决“该用哪个 Python 执行脚本”这个核心问题。
安装 pyenv（macos / linux）
推荐使用官方推荐的安装方式：通过 pyenv-installer 脚本一键安装。
export PYENV_ROOT=”$HOME/.pyenv”
export PATH=”$PYENV_ROOT/bin:$PATH”
eval “$(pyenv init -)”
- 重新加载配置：source ~/.zshrc（或对应配置文件）
- 验证安装：pyenv –version 应输出类似 2.4.12 的版本号
安装与切换 Python 版本
pyenv 会从源码编译安装 Python，因此需提前安装编译依赖（如 macOS 上用 brew install openssl readline sqlite3 xz zlib；ubuntu/debian 上运行 sudo apt-get 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 libexpat1-dev）。
立即学习“Python免费学习笔记（深入）”；
- 查看可安装的版本：pyenv install –list | grep “3.[89]|3.1[0-2]”（筛选常用版本）
- 安装指定版本（例如 3.11.9）：pyenv install 3.11.9
- 查看已安装版本：pyenv versions（带 * 号的是当前生效版本）
- 全局切换（影响整个用户）：pyenv global 3.11.9
- 当前目录局部切换（会生成 .python-version 文件）：pyenv local 3.10.13
- 仅对本次 shell 会话生效：pyenv shell 3.9.18
配合 pyenv-virtualenv 使用（推荐）
单独用 pyenv 只管 Python 解释器，项目依赖隔离还需虚拟环境。pyenv-virtualenv 是官方维护的插件，无缝集成。
- 安装插件（如果未随 pyenv-installer 自动安装）：git clone https://github.com/pyenv/pyenv-virtualenv.git $PYENV_ROOT/plugins/pyenv-virtualenv
- 在 shell 配置中追加一行：eval “$(pyenv virtualenv-init -)”，然后 source 重载
- 创建虚拟环境（基于已安装的 Python 版本）：pyenv virtualenv 3.11.9 myproject-env
- 激活环境：pyenv activate myproject-env（退出用 pyenv deactivate）
- 更常用的方式是绑定到目录：pyenv local myproject-env，进入该目录自动激活
- 删除环境：pyenv virtualenv-delete myproject-env
常见问题与技巧
遇到命令未找到、版本不生效、pip 安装包找不到等问题，多数源于环境未正确加载或路径冲突。
- pyenv 命令不存在？检查 pyenv init 输出是否已写入 shell 配置，并确认执行了 source
- pyenv global 生效但 python –version 不变？可能是其他 Python（如系统自带、Anaconda）仍在 PATH 前面，用 which python 和 echo $PATH 排查
- 安装失败提示 missing zlib？说明缺少编译依赖，按系统补全后再重试
- 想快速回退到系统 Python？执行 pyenv global system（前提是系统 Python 在 PATH 中且可被识别）
- 升级 pyenv 本身？运行 pyenv update