pyenv 指南：一台机器管理多个 Python 版本
pyenv 让你在一台机器上自由安装、切换多个 Python 版本：全局版本、项目级版本、与虚拟环境集成。本文讲解 pyenv 安装与高效用法。
直接回答：pyenv 是 Python 版本管理器：同一台机器并存 3.9/3.12/3.13，按项目目录自动切换解释器版本——老项目维护、新版本尝鲜、兼容性测试全靠它。
为什么需要版本管理
系统自带 Python 不敢动（系统工具依赖它），新项目想用 3.13 的新特性，老项目还钉在 3.9——手动装多份 Python 并管理 PATH 是灾难。pyenv 用 shim 机制拦截 python 命令，按当前目录的版本声明路由到正确解释器。
安装
# macOS
brew install pyenv
# Linux 用安装脚本
curl https://pyenv.run | bash
按提示把 pyenv init 写进 shell 配置，重开终端生效。
日常使用
pyenv install --list | tail # 可安装版本
pyenv install 3.13.2 # 安装
pyenv versions # 已装版本
pyenv global 3.13.2 # 全局默认
pyenv install -s 3.11.9
pyenv local 3.11.9 # 当前目录固定（生成 .python-version）
pyenv install -s 3.12.0
pyenv shell 3.12.0 # 仅当前会话
三层优先级：shell > local（项目目录）> global。项目里 pyenv local 生成的 .python-version 文件提交进版本库，同事仍需安装对应版本并完成 shell 初始化；文件只声明选择，不自动安装解释器。
以上补丁版本仅作命令示例，不是当前安全版本推荐。部署应选择受支持分支的最新安全补丁；Python 3.9 已结束支持，不应用于新部署。pyenv 常需从源码编译，先按官方指南准备系统依赖。
与虚拟环境协作
pyenv 管"哪个 Python"，虚拟环境管"装什么包"——职责互补：
pyenv local 3.12.0
python -m venv .venv
装了 pyenv-virtualenv 插件后更进一步：虚拟环境也纳入 pyenv 统一管理，按目录自动激活。
开发工具链
全局工具（black、poetry）建议用 pipx 安装到各自隔离环境，并让 pipx 指向 pyenv 管理的稳定版本——工具不随项目 Python 版本切换而漂移。
常见问题（FAQ）
Q：pyenv、uv、Mise 怎么分工？
A：三者都能管 Python 版本。2026 年的简化建议：纯 Python 开发者 uv 一家就够（uv python install）；多语言工具链选 Mise；存量 pyenv 用户没痛点继续用。
Q：装版本时编译失败？
A：缺编译依赖（openssl、readline、zlib 的开发头文件）。pyenv 官方 wiki 有各发行版的依赖清单，装齐重试。
Q：为什么 python 还是系统版本？
A：shim 没接管：确认 shell 配置里 pyenv init 已加载且 PATH 中 shim 目录在系统路径之前；pyenv rehash 刷新 shim。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
