个人的 Python 环境配置 cheatsheet
原文参考： Real Python – Managing Multiple Python Versions with pyenv
适用平台： macOS/Linux/WSL
What and Why
pyenv 是轻量级 Python 多版本管理工具，可以帮助用户在不同版本 Python 间切换。
现代语言比如 Rust 使用官方维护的 rustup 来进行版本管理，pyenv 项目是第三方维护，参考 Ruby 语言的 rbenv 和 ruby-build 开发的 Python 语言版本控制工具。
pyenv 主要解决单机多版本 Python 管理问题，并可结合虚拟环境（如 venv 或 pyenv-virtualenv） 实现项目级依赖隔离，防止包污染与冲突。
理解使用 pyenv 的好处
TL;DR 使用
pyenv主要是解决单机器上灵活配置多个 Python 版本（包括 py2 和 py3 ）。此外，为保证不同项目之间的隔离性，使安装的依赖包不污染系统环境或相互冲突，可配合项目独立的虚拟环境实现。
pyenv 是一个专门用于“干净地管理多个 Python 版本”的工具。即使你的操作系统已经预装了 Python，安装 pyenv 仍然非常值得——它可以让系统自带的 Python 保持纯净，更重要的是，让你能方便地参与使用不同 Python 版本的项目。
Q：为什么要用 pyenv，而不是直接使用系统自带的 Python？
系统自带的 Python（system Python）是由操作系统直接安装的解释器。 在 macOS 和 Linux 上通常自带一个默认的系统 Python，而在 Windows 上则通常需要你手动安装。
Q：为什么我们不能直接用系统自带的 Python 来日常开发呢？
你可以这样理解：系统的 Python “属于操作系统”。 在很多情况下，操作系统本身的某些组件依赖于这个特定版本的 Python 才能正常工作。 如果你更改了系统 Python 的版本，或修改了它自带的包，很可能导致系统功能出错甚至损坏。
此外，你对系统 Python 的版本往往没有太多控制权。 举例来说，如果你在 Ubuntu 上想使用 Python 的最新特性，可能会发现：官方软件源中的 Python 版本太旧； 需要等待新版本的操作系统发布；等待的过程中，Python 又出了更高版本。结果就是，你始终无法保持“最新版本”。
如果你使用 pip 或类似工具在系统 Python 上安装第三方包，这些包会被安装到全局环境中。 这样会带来问题：当其他用户（或是你自己）想安装不同版本的同一个包来做另一个项目时，在全局环境中你无法获得同一个包的多个版本。
在多数操作系统中，安装新的 Python 版本或第三方包都需要管理员权限。 这在有严格安全策略的企业环境中尤其麻烦，因为你可能得等管理员帮你安装。总之直接使用系统 Python 有以下弊端：
- 部分破坏操作系统
- 无法使用最新 Python 版本
- 依赖旧版本的项目出现问题
- 依赖新特性的项目无法开发
- 安装依赖需要管理员介入
✅ 理想的方案：灵活且安全的 Python 环境管理
对于开发者而言，理想的 Python 管理方式应该允许你：
- 在用户空间安装 Python，无需管理员权限；
- 自由地安装、管理、卸载多个 Python 版本；
- 为不同项目指定确切的 Python 版本；
- 随时在多个版本之间切换。
好消息是，pyenv 能实现以上所有功能。此外，它还支持安装 Python 的预发布版本（pre-release）， 方便你提前体验新语言特性或测试新版本的兼容性与潜在问题。
多版本管理工具对比表
| 特性 | 🦀 Rust – rustup | 🐍 Python – pyenv | 💎 Ruby – rbenv |
|---|---|---|---|
| 维护方 | 官方 | 社区 | 社区 |
| 管理对象 | 编译器与工具链 | Python 解释器版本 | Ruby 解释器版本 |
| 版本切换机制 | 工具链级别 | 解释器级别 | 解释器级别 |
| 隔离机制 | 工具链独立 | 可配合 venv 或 pyenv-virtualenv | 可配合 gemset 或插件 |
| 路径机制 | ~/.cargo/bin shim | PATH shim + 环境变量 | PATH shim + 环境变量 |
| 跨平台支持 | macOS / Linux / Windows | macOS / Linux / WSL | macOS / Linux |
| 与包管理器关系 | 内建 cargo | 配合 pip / poetry | 配合 bundler |
精简整理自 GPT5
安装 pyenv
参考 Installation of pyenv | GitHub
对于 macOS 用户可以方便的从 Homebrew 下载
brew update
brew install pyenv
安装完成后，在你的 ~/.zshrc 或 ~/.zprofile （bash 则为~/.bashrc 或 ~/.bash_profile）末尾添加：
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"
# or
# eval "$(pyenv init - bash)"
核心机制
pyenv 通过一个 “shim 层” 实现版本控制，当 shell 中运行 python 或 pip 命令时：
- shell 首先命中
~/.pyenv/shims/python（被 shim 层劫持） - shim 层会根据你的配置 (global/local/shell) 自动转发到正确的解释器
可以通过 which python 观察到命令被劫持，以及 pyenv which python 确认实际运行的解释器。
which python
# /Users/user_name/.pyenv/shims/python
pyenv which python
# /Users/user_name/.pyenv/versions/3.14.0/bin/python
安装与切换 Python 版本
列出可安装版本：
pyenv install --list
安装指定版本
pyenv install 3.12.3
pyenv install 3.14.0
设置全局版本（影响所有 shell） .python-version 文件生成在用户根目录 ~/.pyenv 中：
pyenv global 3.14.0
设置本地版本（仅当前目录） .python-version 在当前目录：
pyenv local 3.12.3
虚拟环境配合 pyenv-virtualenv 使用
在 macOS 环境中，python -m venv 设置的虚拟环境，有时会因 pyenv 的 shim 层劫持导致环境激活异常，建议统一使用 pyenv 和配套插件管理基础版本与虚拟环境。
安装 pyenv-virtualenv 插件：
brew install pyenv-virtualenv
在 ~/.zshrc 末尾额外增加初始化 （bash 为~/.bashrc）：
eval "$(pyenv virtualenv-init - zsh)"
# or
# eval "$(pyenv virtualenv-init - bash)"
新建虚拟环境，此处以 3.14.0 环境为基，虚拟环境名称为 venv-name：
pyenv virtualenv 3.14.0 venv-name
需要指出的是与 python -m venv .venv 不同，默认并不是在当前工作目录建立， pyenv 将虚拟环境统一到~/.pyenv 中管理：
列出安装的所有版本，或者使用pyenv virtualenvs：
pyenv versions
system
3.9.24
3.12.12
* 3.14.0 (set by /Users/user_name/.pyenv/version)
3.14.0/envs/venv-name
venv-name --> /Users/user_name/.pyenv/versions/3.14.0/envs/venv-name
清晰显示环境之间的实际关系。使用 pyenv activate venv-name 启动虚拟环境， pyenv deactivate 退出当前环境。