核心是“不碰系统、版本隔离、按需切换”：pyenv在用户目录安装多个完整可写的Python版本，避开系统Python权限限制，通过shell shim动态接管命令，支持全局/目录/会话级版本切换。
mac 上用 pyenv 安装 python，核心是“不碰系统、版本隔离、按需切换”。系统自带的 python（比如 macos sequoia 自带的 3.9.6）权限受限、没 pip、不能装包，直接用它开发会频繁报错。pyenv 的作用，就是绕开它，在你自己的用户目录里，干净地装多个完整、可写、可编译的 python 版本。
安装前先确认几个关键前提
- 终端用的是 zsh（macOS Catalina 及以后默认，
echo $SHELL可确认） - 已装 Xcode 命令行工具（
xcode-select --install，点安装即可） - 推荐已装 Homebrew（后续依赖和 pyenv 都靠它，没装就先运行：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"）
安装 pyenv 并配置环境
pyenv 本身不是 Python，而是一个“版本调度器”，它把不同 Python 解释器装在 ~/.pyenv/versions/ 下，再通过 shell shim 动态接管 python 和 pip 命令。
执行三步一次性配置（全部复制粘贴到终端回车）：
brew install pyenv echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc source ~/.zshrc
验证是否生效：pyenv --version → 应输出类似 2.4.0 的版本号pyenv versions → 初次运行会显示 * system（表示当前用的是系统 Python）
立即学习“Python免费学习笔记（深入）”；
装 Python 版本前，必须装编译依赖
pyenv 是从源码编译安装 Python 的，缺底层库会卡在 configure 或 make 阶段。尤其 M 系列芯片（ARM64）需额外链接 OpenSSL 和 zlib：
brew install openssl readline sqlite3 xz zlib tcl-tk # Apple Silicon（M1/M2/M3）额外设置（防止编译失败） 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 版本
列出所有可用版本（只看稳定版）：
pyenv install --list | grep "^\s*[0-9]\+\.[0-9]\+\.[0-9]\+$"
选一个主流版本安装，比如 3.12.5（新项目推荐）或 3.11.9（兼容性更广）：
pyenv install 3.12.5
编译过程约 2–5 分钟，终端会有进度日志。成功后：
pyenv versions # 会看到 3.12.5 出现在列表里，但还没激活
切换方式有三种，按场景选：
-
全局默认（新开终端都用这个）：
pyenv global 3.12.5 -
当前目录专用（进项目文件夹后执行）：
pyenv local 3.11.9（会在该目录生成.python-version文件） -
仅本次终端有效：
pyenv shell 3.10.13
切换后验证：
python --version # 应显示你设的版本，如 3.12.5 which python # 路径类似 /Users/xxx/.pyenv/versions/3.12.5/bin/python
小提示：避免常见坑
- 不要用
sudo pip install—— pyenv 安装的 Python 自带 pip，且有完整写入权限，pip install直接可用 - 不要手动改
/usr/bin/python3或试图卸载系统 Python —— SIP 保护下会失败，还可能影响系统功能 - 如果
pyenv install报错说No such file or directory: 'openssl'，说明依赖没装全，重新运行brew install openssl ...并检查source ~/.zshrc是否执行 - 想知道某个版本装在哪？
pyenv prefix 3.12.5会输出完整路径，方便调试或集成 IDE
不复杂但容易忽略
