定义
pyenv 是一个面向 Python 的命令行版本管理工具，作用是让使用者方便地在多个 Python 版本之间切换。它的自我定位是简单、不打扰使用者，并遵循 Unix 单一职责工具的传统[5]。
从功能上看，pyenv 可以按用户修改全局 Python 版本、为单个项目指定版本、用环境变量临时覆盖版本，还可以同时在多个版本中检索命令，这一点在配合 tox 做跨版本测试时有用[3]。它自身只负责解释器版本这一件事，虚拟环境的创建与切换由 virtualenv、venv 等工具或相应插件承担[6]。
与依赖 Python 自身运行的同类工具不同，pyenv 由纯 Shell 脚本实现，因而不存在引导（bootstrap）问题[3]。开源许可证为 MIT[7]。
原理
pyenv 的核心机制是垫片与 PATH 的顺序。操作系统执行 python、pip 这类命令时，会从左到右遍历 PATH 中列出的目录，先找到的可执行文件先被执行[2]。pyenv 把自己存放垫片的目录放在 PATH 最前面，于是同名命令会先命中垫片[2]。
垫片本身是很小的可执行脚本，并不包含 Python，而是把命令转交给 pyenv。每个垫片通过调用 pyenv which 并传入自己的文件名来确定真正要执行的程序，再把参数原样传递过去[8]。垫片由 rehash 过程生成：扫描每个已安装版本的可执行文件目录，为其中的命令建立对应垫片，因此新装版本或插件后有时需要手动执行重新生成[8]。
版本选择有明确的优先级顺序：先看 PYENV_VERSION 环境变量，再看当前目录下的 .python-version 文件，然后沿父目录逐级向上查找该文件直到文件系统根目录，最后看全局版本文件；若全局文件不存在，则视为使用系统自带的 Python[2]。每个版本安装在独立目录下，对 pyenv 而言版本名就是这些目录名[9]。
pyenv init 会在 shell 启动时把垫片目录前置到 PATH，并可重新生成垫片；若只想启用垫片而不要 shell 集成，可以改用只做环境准备的形式[1]。多个版本也可同时生效，此时命令会按给定顺序依次在各版本中查找[4]。
发展历程
pyenv 从 rbenv 和 ruby-build 派生而来，并针对 Python 做了修改，因此沿用了前者的垫片式思路[3][10]。其代码仓库于 2012 年建立，长期以 Shell 实现并采用 MIT 许可证发布[11][7]。
在 pyenv 之前，Python 领域已有 pythonbrew、pythonz 等版本管理工具。pythonbrew 项目其后不再活跃开发，并在主页上引导使用者改用 pyenv，pyenv 因而逐渐接替了这类工具的位置[12]。
2.3.0 版本对 shell 启动配置做了简化，此前 2.0.0 至 2.2.5 使用的较复杂配置方式仍然可以继续工作[4]。发行版也陆续收录该工具，例如 Debian 打包的版本为 2.7.1。
应用
pyenv 主要用于同一台机器上并存多个 Python 版本的开发场景：老项目依赖旧版本、新项目使用新版本时，可分别为项目固定解释器，避免互相干扰[13]。它也可用于安装并试用预发布版本或最新开发版，以便在升级前检查兼容性[13]。
常用操作包括列出可安装版本、安装指定版本，以及用 global、local、shell 三个命令分别设置全局、项目目录和当前会话的版本[6]。其中 local 会在目录中写入 .python-version 文件记录版本，便于随代码仓库共享同一解释器约定[6]。
在持续集成、测试与依赖管理流程中，pyenv 常与 tox、Poetry、Pipenv 等工具配合使用，由它提供解释器、由其他工具负责依赖与虚拟环境。它也提供 Python 之外的实现版本支持，例如 PyPy[6]。
局限
pyenv 本身不管理虚拟环境，虚拟环境的创建与激活需要 virtualenv、venv 等工具，或额外安装 pyenv-virtualenv 插件来完成；由于这些虚拟环境的激活脚本会修改 PATH，可能与垫片式命令拦截相互干扰[9]。
原生 pyenv 不适用于 Windows，在该系统上需使用社区维护的移植版本 pyenv-win，两者虽源自同一套思路，但个别子命令与更新节奏存在差异[1][14]。pyenv 的定位仅是解释器版本管理，不承担依赖解析与锁文件等项目管理职责[14]。
由于垫片目录只需放在 PATH 前端，若系统或其他软件在 PATH 中插入了优先级更高的 Python 路径，pyenv 的切换就会看似失效；此外，父目录中遗留的 .python-version 文件会覆盖全局设置，可能造成版本与预期不符[14][15]。安装 Python 版本需从源代码构建，因此依赖一系列编译工具与开发库，安装耗时较长[13]。
参见
-
Python —— pyenv 所管理的编程语言运行环境。
-
rbenv —— pyenv 由其派生并沿用垫片式版本切换思路。
-
virtualenv —— 负责创建隔离环境，与 pyenv 的版本管理职责互补。
-
tox —— 常借助 pyenv 提供的多版本解释器做跨版本测试。
-
PyPy —— pyenv 可安装的 Python 实现之一。
参考资料
- README [引用日期2026-10-14]
- Understanding PATH [引用日期2026-10-14]
- pyenv，一个python的小工具 [引用日期2026-10-14]
- pyenv/pyenv: Simple Python version management · GitHub [引用日期2026-10-14]
- Simple Python Version Management: pyenv [引用日期2026-10-14]
- pyenv | Python Tools – Real Python [引用日期2026-10-14]
- github.com/pyenv/pyenv - Ecosyste.ms: OpenCollective [引用日期2026-10-14]
- Shim System | pyenv/pyenv | DeepWiki [引用日期2026-10-14]
- pyenv.1.en [引用日期2026-10-14]
- Meta Configuration of Package pyenv [引用日期2026-10-14]
- pyenv/pyenv [引用日期2026-10-14]
- Linux——Django 开发环境部署（二）python版本控制器pyenv [引用日期2026-10-14]
- pyenv 管理多个 Python 版本(1) [引用日期2026-10-14]
- pyenv 与 uv 版本管理 | FANDEX [引用日期2026-10-14]
- stackoverflow.com 上的网页 [引用日期2026-10-14]