本文介绍了在macOS上使用pyenv管理多Python版本的高效方案。通过Homebrew安装pyenv后，可轻松安装多个Python版本（如3.7、3.8、3.9等），并通过global、local、shell三个层级灵活切换版本，优先级依次递增。结合pyenv-virtualenv插件还能创建隔离的虚拟环境。这种方法避免了直接修改环境变量的风险，确保了开发环境的整洁与灵活性，特别适合需要维护不同Python版本项目的开发者。

博主博客

为什么需要管理多个Python版本？

目前Python同时维护着Python 2和Python 3两个主要版本系列。虽然Python 2已于2020年停止官方支持，但在实际开发中，我们仍然可能遇到以下情况：

  • 维护遗留项目需要使用Python 2
  • 不同项目依赖不同版本的Python 3（如3.6、3.7、3.8等）
  • 测试代码在不同Python版本下的兼容性
  • 某些库或框架对特定Python版本有要求

传统的环境变量修改方法虽然可行，但不够优雅且容易出错。下面介绍一种更加高效的解决方案。

安装Homebrew

Homebrew 是macOS下高效的命令行软件包管理器，是macOS必备工具之一。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后验证：

brew -v

输出示例：

Homebrew 3.6.9
Homebrew/homebrew-core (git revision 5707e; last commit 2023-07-09)

安装pyenv

pyenv是一个优秀的Python版本管理工具，可以轻松切换不同Python版本。

# 更新Homebrew
brew update

# 安装pyenv
brew install pyenv

# 配置shell环境（根据使用的shell选择）
# 对于bash用户，将以下内容添加到 ~/.bashrc 或 ~/.bash_profile：
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(pyenv init -)"' >> ~/.bash_profile

# 对于zsh用户，将以下内容添加到 ~/.zshrc：
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# 重新加载配置
source ~/.bash_profile  # 或 source ~/.zshrc

# 验证安装
pyenv -v

输出示例：

pyenv 2.3.6

安装Python编译依赖

在安装Python之前，需要确保系统有必要的编译工具和依赖：

# 安装Xcode命令行工具（如果尚未安装）
xcode-select --install

# 安装Python编译依赖
brew install openssl readline sqlite3 xz zlib

安装和管理多个Python版本

查看可安装的Python版本

# 查看所有可安装的Python版本
pyenv install --list

# 查看可安装的Python 3版本
pyenv install --list | grep " 3\."

安装特定Python版本

# 安装Python 3.7.0
pyenv install 3.7.0

# 安装Python 3.8.12
pyenv install 3.8.12

# 安装Python 3.9.7
pyenv install 3.9.7

# 安装Python 3.10.2
pyenv install 3.10.2

# 安装Python 3.11.0
pyenv install 3.11.0

查看已安装的版本

pyenv versions

输出示例：

* system (set by /Users/username/.pyenv/version)
  3.7.0
  3.8.12
  3.9.7
  3.10.2
  3.11.0

注：星号(*)表示当前激活的版本

切换Python版本

pyenv提供了三种不同范围的版本控制：

1. 全局版本（global）

设置全局默认的Python版本：

# 设置全局Python版本为3.9.7
pyenv global 3.9.7

# 验证当前Python版本
python --version

# 输出：Python 3.9.7
pyenv versions

输出示例：

  system
  3.7.0
  3.8.12
* 3.9.7 (set by /Users/username/.pyenv/version)
  3.10.2
  3.11.0

2. 本地版本（local）

为特定项目目录设置Python版本：

# 进入项目目录
cd /path/to/your/project

# 设置该目录使用Python 3.8.12
pyenv local 3.8.12

# 这会在当前目录创建 .python-version 文件
cat .python-version
# 输出：3.8.12

3. Shell会话版本（shell）

为当前Shell会话临时设置Python版本：

# 在当前Shell中使用Python 3.7.0
pyenv shell 3.7.0

# 退出当前Shell或打开新Shell时会恢复原版本

版本优先级

当同时设置了多个范围的版本时，优先级为：
shell > local > global

版本管理技巧

设置多个全局版本

可以设置多个全局版本，pyenv会按顺序查找可用的Python版本：

# 设置多个全局版本，优先使用3.9.7，如果不可用则使用3.8.12
pyenv global 3.9.7 3.8.12

恢复系统Python版本

# 将全局版本恢复为系统自带的Python
pyenv global system

卸载Python版本

# 卸载指定的Python版本
pyenv uninstall 3.7.0

pyenv常用命令详解

# 查看所有可用命令
pyenv commands

# 设置或显示本地的Python版本
pyenv local 3.9.7          # 设置本地版本
pyenv local                 # 显示本地版本
pyenv local --unset        # 取消本地版本设置

# 设置或显示全局Python版本
pyenv global 3.9.7         # 设置全局版本
pyenv global               # 显示全局版本

# 设置或显示shell指定的Python版本
pyenv shell 3.9.7          # 设置shell版本
pyenv shell               # 显示shell版本
pyenv shell --unset       # 取消shell版本设置

# 安装指定Python版本
pyenv install 3.11.0

# 卸载指定Python版本
pyenv uninstall 3.7.0

# 显示当前的Python版本及其本地路径
pyenv version

# 查看所有已经安装的版本
pyenv versions

# 显示指定命令的安装路径
pyenv which python
pyenv which pip

# 查看pyenv的根目录
pyenv root

# 重新整理已安装的版本（在安装新版本后运行）
pyenv rehash

虚拟环境管理

除了版本管理，还建议结合虚拟环境使用：

使用pyenv-virtualenv（推荐）

# 安装pyenv-virtualenv插件
brew install pyenv-virtualenv

# 配置shell（添加到 ~/.bash_profile 或 ~/.zshrc）
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bash_profile
source ~/.bash_profile

# 创建虚拟环境
pyenv virtualenv 3.9.7 my-project-env

# 使用虚拟环境
pyenv activate my-project-env

# 退出虚拟环境
pyenv deactivate

# 删除虚拟环境
pyenv uninstall my-project-env

使用venv（Python 3.3+内置）

# 创建虚拟环境
python -m venv myenv

# 激活虚拟环境
source myenv/bin/activate

# 退出虚拟环境
deactivate

故障排除

安装Python时编译失败

如果遇到编译错误，可以尝试：

# 确保所有依赖已安装
brew install openssl readline sqlite3 xz zlib

# 对于某些版本，可能需要设置编译标志
export LDFLAGS="-L/usr/local/opt/zlib/lib -L/usr/local/opt/bzip2/lib"
export CPPFLAGS="-I/usr/local/opt/zlib/include -I/usr/local/opt/bzip2/include"

命令找不到

如果pyenv命令找不到，请确保：

  1. 正确配置了shell配置文件（.bash_profile或.zshrc）
  2. 执行了source ~/.bash_profile或source ~/.zshrc
  3. 重启终端或开启新的Shell会话

总结

通过pyenv管理多个Python版本，我们可以：

  • 轻松在不同项目间切换Python版本
  • 保持系统Python环境的干净
  • 测试代码在不同Python版本的兼容性
  • 避免因修改系统Python版本导致的系统问题

这种方法比直接修改环境变量更加安全、灵活，是macOS上管理Python版本的推荐方案。

结合虚拟环境使用，可以进一步隔离项目依赖，创建更加干净的开发环境。