pyenv

Python 版本管理器

补充说明

pyenv 通过 shim 切换多个 Python 版本，不依赖系统包管理器。它只管理解释器版本；项目依赖仍应放在 venv、uv 或 poetry 里。

常用示例

pyenv install --list
pyenv install 3.12.7
pyenv versions
pyenv global 3.12.7
pyenv local 3.12.7
pyenv shell 3.12.7
pyenv version
pyenv which python
pyenv rehash
pyenv root
pyenv init

易错点与排错

• shim 目录必须在 PATH 前面；否则系统 Python 会抢先被执行。
• 安装新版本后通常要 pyenv rehash；命令找不到先试这个。
• 优先级是 shell > local > global；排查版本先看 pyenv version 和三个层级。
• pyenv init 要写入 shell 配置；只安装不初始化不会自动切换。
• 编译 Python 需要系统依赖（openssl、zlib、readline 等）；安装失败看构建日志。
• pyenv virtualenv 来自插件，不是 pyenv 内置；没装插件会报未知命令。
• 系统 Python 被替换会影响系统工具；不要 pyenv global system 后随意删版本。
• 与 conda、uv、asdf 混用时 PATH 冲突；只保留一种版本管理方式。

相关命令

• python — 解释器
• uv — 项目与依赖管理
• asdf / mise — 多语言版本管理