pyenv 通过 shell 初始化钩子劫持 python 命令,依赖 export PYENV_ROOT、export PATH="$PYENV_ROOT/bin:$PATH" 和 eval "$(pyenv init -zsh)" 三行顺序配置,缺一不可;手动拼接 PATH 会冲突导致版本错乱。

pyenv 不是 alias 或 PATH 手动拼接工具,它靠 shell 初始化钩子劫持 python 命令调用路径。直接改 ~/.zshrc 里硬写 export PATH="/some/python/bin:$PATH" 会和 pyenv 冲突,导致 which python 指向错误、pyenv local 失效、甚至 pip 安装包跑到系统 Python 下。
必须按顺序配置 ~/.zshrc 的三行
新版 macOS(zsh 默认)只认这三行,缺一不可,顺序也不能错:
export PYENV_ROOT="$HOME/.pyenv"export PATH="$PYENV_ROOT/bin:$PATH"-
eval "$(pyenv init -zsh)"(注意是-zsh,不是-或--path)
写完立刻执行 source ~/.zshrc,再验证:pyenv --version 有输出、pyenv versions 至少显示 system。如果报 command not found: pyenv,说明第三行没生效或写错了参数。
安装 Python 版本前先装编译依赖
macOS 自带的 OpenSSL 和 zlib 路径与 pyenv 编译器不兼容,尤其 M 系列芯片容易卡在 zlib not found 或 openssl headers missing。别跳过这步:
- 通用依赖:
brew install openssl readline sqlite3 xz zlib tcl-tk - M 系列芯片额外运行:
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 - 老版本(如 3.8.x)可能需加环境变量:
PYTHON_CONFIGURE_OPTS="--with-openssl=$(brew --prefix openssl@3)" pyenv install 3.8.20
漏装依赖的典型表现:安装过程卡住、最后报 BUILD FAILED、日志末尾出现 ModuleNotFoundError: No module named '_ctypes' 或 zlib extension was not compiled。
Camoufox 是一个基于 Firefox 构建的开源反检测浏览器,为 Python 自动化工作流程提供强大的指纹注入和反机器人检测规避功能。它与 Playwright 集成,以提供能够绕过现代机器人检测系统的隐身浏览能力。
立即学习“Python免费学习笔记(深入)”;
切换版本时作用域必须分清
pyenv global、pyenv local、pyenv shell 互不覆盖,但优先级严格:shell > local > global。容易混淆的点:
-
pyenv global 3.11.9只影响新打开的终端,当前终端不会变——得关掉重开或手动pyenv shell 3.11.9 -
pyenv local 3.12.5在项目根目录生成.python-version文件,内容就是纯文本3.12.5;删掉它就退回到 global,不是pyenv local --unset才能删(该命令已弃用) -
pyenv shell 3.12.5的效果仅限当前终端窗口,关闭即消失;误用后发现python --version死活不变,大概率是它还在生效,运行pyenv shell --unset清除
每次切换后务必验证:python --version 和 which python 必须同时指向 ~/.pyenv/versions/3.x.x/bin/python,否则 pip 安装的包会进错地方。
最常被忽略的是:系统自带的 python 命令在 macOS 12.3+ 后已被移除,仅保留 python3。如果你没配 alias python=python3,又没用 pyenv 装任何版本,python 就真会报 command not found——这不是 pyenv 故障,是 macOS 的默认行为。

















