本指南介绍如何通过 Homebrew 安装 pyenv，并利用其在 macOS 上优雅地切换不同版本的 Python 和管理对应的 pip 环境。

安装前置工具 (Homebrew)

如果尚未安装 Homebrew（Mac 的包管理器），请先执行：

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

安装 pyenv

使用 Homebrew 安装 pyenv 核心组件：

brew updatebrew install pyenv xz

注：xz 是为了解压某些 Python 安装包所需的依赖。

配置环境变量 (核心步骤)

为了让 pyenv 能够自动拦截 python 和 pip 命令（即 Shim 机制），必须在 Shell 配置文件中添加相关路径。

对于 macOS 默认的 Zsh，请编辑 ~/.zshrc：

# 打开配置文件nano ~/.zshrc

# 将以下内容添加到文件末尾
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# 保存并退出 (Ctrl+O, Enter, Ctrl+X)
# 使配置立即生效
source ~/.zshrc

pyenv 常用管理命令

安装 Python

pyenv install --list        # 查看所有可供安装的版本
pyenv install 3.10.12       # 安装指定版本

查看已安装版本

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

切换版本

pyenv 提供了三个作用域的版本控制：

  • Global (全局)：整个系统的默认版本。
pyenv global 3.10.12
  • Local (局部)：推荐用法。仅在当前目录及子目录下生效（会自动创建 .python-version 文件）。
pyenv local 3.9.5
  • Shell (会话)：仅对当前打开的终端窗口有效。
pyenv shell 3.11.0

pip 管理与工作原理

自动同步

在 pyenv 环境下，你不需要手动管理多个 pip。

  • 当你切换 Python 版本时，pip 会通过 pyenv 的 Shim (垫片) 机制自动指向当前活跃版本的 Python 库目录。
  • 验证方法：执行 pip --version，你会发现其路径位于 ~/.pyenv/shims/pip。

pip 常用操作

  • 升级当前版本的 pip：
pip install --upgrade pip
  • 刷新索引（安装了带命令行工具的库，如 Flask, Pytest 后，若命令不生效请执行）：
pyenv rehash

进阶：隔离项目环境 (pyenv-virtualenv)

为了防止不同项目之间的第三方库冲突，建议配合虚拟环境插件使用。

  1. 安装插件：brew install pyenv-virtualenv
  2. 配置：在 ~/.zshrc 中添加 eval "$(pyenv virtualenv-init -)"。
  3. 使用示例：
# 创建基于 3.10.12 的虚拟环境pyenv virtualenv 3.10.12 my-project-env# 在项目文件夹下激活pyenv local my-project-env

避坑指南

  1. 不要使用 sudo：使用 pyenv 安装 Python 或使用 pip 安装库时，严禁使用 sudo，否则会破坏权限结构。
  2. 编译失败：如果安装 Python 时报错，通常是由于缺少 Xcode 命令行工具，请执行：
xcode-select --install