一、安装 Pyenv 及环境配置

1. 安装 Pyenv

终端执行以下命令，通过 Homebrew 安装 Pyenv：

brew install pyenv

2. 配置 Pyenv 环境变量

M4 芯片 Mac 默认使用 zsh 终端，需将 Pyenv 配置写入终端配置文件 ~/.zshrc，确保每次打开终端都能识别 Pyenv。依次执行以下 3 行命令：

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

配置生效：

source ~/.zshrc

3. 补充配置：解决 “command not found: python”

Mac 系统默认只有 python3 命令，没有 python 命令，需添加别名让两者通用，避免后续使用报错。执行：

echo 'alias python="python3"' >> ~/.zshrc
source ~/.zshrc

至此，Pyenv 安装配置全部完成，接下来就是核心用法。

三、Pyenv 核心用法

以下命令覆盖 “查看-安装-切换-卸载” 全流程，记熟这几条就够日常使用。

1. 查看版本相关

• 查看已安装的 Python 版本（带* 的是当前正在使用的版本）： pyenv versions
• 查看可安装的 Python 版本（所有可用版本列表）： pyenv install --list
• 查看当前使用的 Python 版本： python --version

2. 安装 Python 版本

根据项目需求安装对应版本，分两种情况（适配 M4 芯片）：

• 正常版本（3.9+，无需额外配置）： pyenv install 3.10.15（以 3.10.15 为例，可替换为其他版本）
• 老版本（3.8/3.7，解决 openssl 报错）： PYTHON_CONFIGURE_OPTS="--with-openssl=$(brew --prefix openssl@3)" pyenv install 3.8.20（以 3.8.20 为例）

3. 切换 Python 版本（3 种模式，按需选择）

Pyenv 支持 3 种切换方式，覆盖全局、项目、临时场景，完美实现环境隔离。

• 全局切换（整个系统生效，适合设置常用版本）： pyenv global 3.10.15
• 项目切换（当前文件夹生效，自动隔离不同项目）： 进入项目文件夹后执行 pyenv local 3.8.20，后续进入该文件夹会自动切换到对应版本，退出则恢复全局版本。
• 临时切换（当前终端生效，关掉终端失效）： pyenv shell 3.12.7

4. 卸载 Python 版本（无需的版本可清理）

pyenv uninstall 3.8.20（替换为需要卸载的版本号）

5. Python 基础使用（切换版本后）

• 运行 Python 交互环境： python
• 运行 Python 文件： python 文件名.py（如 python test.py）
• 安装第三方库（如 requests、pandas）： pip install 库名（pip 会自动适配当前 Pyenv 版本，不会混乱）

四、Pyenv 安装常见报错及解决方案（M4 芯片必看）

在 M4 芯片 Mac 上安装 Python 时，最容易遇到 2 类报错，以下是具体原因和一步到位的解决方案，亲测有效。

报错 1：ModuleNotFoundError: No module named '_lzma'

报错场景

执行 pyenv install 3.10.15 时，出现如下报错：

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/Users/zwy/.pyenv/versions/3.10.15/lib/python3.10/lzma.py", line 27, in <module>
    from _lzma import *
ModuleNotFoundError: No module named '_lzma'

报错原因

M4 芯片系统缺少 lzma 压缩库，导致 Python 编译时跳过该模块，虽不影响 Python 主体安装，但后续安装第三方库会报错。

解决方案

# 1. 安装缺失的 lzma 依赖（即 xz 库）
brew install xz

# 2. 卸载刚才安装失败的 Python 版本
pyenv uninstall 3.10.15

# 3. 重新安装 Python
pyenv install 3.10.15

安装完成后，输入 python --version，无红色报错即修复成功。后续安装任何 Python 版本，都不会再出现该问题。

报错 2：Error: No available formula with the name "openssl@1.1"

报错场景

执行 pyenv install 3.8.20（老版本 Python）时，出现如下报错：

Error: No available formula with the name "openssl@1.1". Did you mean openssl@3.5, openssl@3.0 or openssl@3?

报错原因

Python 3.8 及以下老版本，默认依赖 openssl@1.1，但 2025 年后的 Homebrew 已删除该版本，仅保留 openssl@3，导致版本不兼容。

解决方案

强制让老版本 Python 适配系统已有的 openssl@3，执行以下命令安装：

PYTHON_CONFIGURE_OPTS="--with-openssl=$(brew --prefix openssl@3)" pyenv install 3.8.20

提示：后续安装任何老版本 Python（3.7/3.8/3.9），都可沿用该命令，只需替换版本号即可。

只需安装xz，其他mac系统默认已安装

#brew install zlib bzip2
#brew install readline openssl@3