MacOS 使用 pyenv + brew 优雅管理 Python 多版本环境

本文采用「pyenv + Homebrew」方案，为 MacOS 搭建干净、隔离的 Python 多版本环境，彻底避免污染系统自带 Python，完美适配不同项目版本需求。

一、前置依赖安装（必做）

Python 编译安装需依赖 Xcode 命令行工具和一系列编译库，首先确保你的 Mac 安装了必要的依赖，避免后续报错。

Xcode 命令行工具和 Homebrew 的安装可以参考我的另一篇教程：MacOS 国内镜像一键安装 Homebrew-CSDN博客

安装完成后，执行 brew -v 验证，输出版本号（如 brew 4.2.18）即表示安装/升级成功。

二、安装并配置 pyenv

pyenv 是一款轻量的 Python 版本管理工具，可轻松实现多版本切换，先完成 pyenv 的安装和环境配置。

2.1 安装 pyenv

通过 Homebrew 快速安装 pyenv，执行命令：

bash 复制代码

brew install pyenv

2.2 配置 pyenv 环境变量

macOS 使用 zsh 终端，无需区分终端类型，直接执行以下命令，将 pyenv 配置写入环境变量文件：

bash 复制代码

# 写入环境变量配置
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

2.3 使配置立即生效

配置写入后，需重新加载环境变量，执行命令：

bash 复制代码

source ~/.zshrc

2.4 验证 pyenv 安装

执行以下命令，若输出版本号（如 pyenv 2.3.34），则表示 pyenv 安装配置成功：

bash 复制代码

pyenv -v

三、安装 Python 编译依赖（必装，防编译失败）

执行以下命令安装 Python 编译依赖，防止 Pyenv 下载 Python 时安装编译失败：

bash 复制代码

brew install openssl readline sqlite3 xz zlib tcl-tk

Apple Silicon 额外配置（M 系列芯片）：

bash 复制代码

echo 'export LDFLAGS="-L/opt/homebrew/opt/zlib/lib -L/opt/homebrew/opt/openssl/lib"' >> ~/.zshrc
echo 'export CPPFLAGS="-I/opt/homebrew/opt/zlib/include -I/opt/homebrew/opt/openssl/include"' >> ~/.zshrc
source ~/.zshrc

四、安装与管理 Python 版本

4.1 查看可安装版本

bash 复制代码

pyenv install --list

4.2 安装指定 Python 版本

执行 pyenv 安装命令安装常用版本（比如 3.13.3），自动下载 Python 源码并编译安装：

bash 复制代码

pyenv install 3.13.3

⚠️ 注意：安装耗时约 2-5 分钟，取决于网络速度和芯片性能，安装过程中终端会显示编译进度，耐心等待即可，不要中途中断命令。

4.3 设置生效版本

全局默认（所有终端生效，推荐）

bash 复制代码

pyenv global 3.13.3

项目局部（仅当前目录生效）

bash 复制代码

pyenv local 3.13.3

当前终端临时（仅本次会话生效）

bash 复制代码

pyenv shell 3.13.3

4.4 刷新版本缓存

bash 复制代码

pyenv rehash

4.5 验证环境

bash 复制代码

# 验证 Python 版本
python --version

# 验证 pip 版本
pip --version

# 查看已安装的 Python 版本（* 号表示当前生效）
pyenv versions

带 * 的版本为当前生效版本

五、常用操作：版本管理与包管理

5.1 pyenv 版本管理常用命令

bash 复制代码

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

# 切换全局版本（示例：切换到 3.11.5）
pyenv global 3.11.5

# 切换当前终端临时版本（仅当前会话生效）
pyenv shell 3.12.0

# 卸载指定 Python 版本（示例：卸载 3.9.18）
pyenv uninstall 3.9.18

# 刷新 pyenv 版本缓存（切换版本后若不生效，执行此命令）
pyenv rehash

5.2 pip 包管理常用命令

pip 是 Python 自带的包管理工具，安装完成后需先升级到最新版本，再进行包安装操作。

bash 复制代码

# 升级 pip 到最新版本
pip install --upgrade pip

# 安装第三方包（示例：安装 requests 库）
pip install requests

# 安装指定版本的第三方包（示例：安装 requests 2.31.0）
pip install requests==2.31.0

# 卸载第三方包
pip uninstall requests -y

# 导出当前环境的包列表（用于项目依赖复刻）
pip freeze > requirements.txt

# 从依赖文件批量安装包
pip install -r requirements.txt