必须用arm64原生Python，否则科学计算和深度学习包会因架构错配报“no matching distribution”或编译失败；需验证arch和platform.machine()均为arm64，禁用Rosetta，使用Homebrew或Miniforge安装，并确保PATH中arm64路径优先。
必须用 arm64 原生 Python，否则后续所有科学计算、深度学习包都会卡在 no matching distribution 或编译失败——这不是 pip 问题，是架构错配。
确认当前终端和 Python 是否真为 arm64
很多人以为打开终端就是 arm64，其实可能被 Rosetta 暗中接管。先运行：
arch<br>python3 -c "import platform; print(platform.machine())"
两个输出都必须是 arm64。如果任一为 x86_64：
- 右键“终端”App → “显示简介” → 取消勾选“使用Rosetta打开”，重启终端
- 别用
/usr/bin/python3（系统自带，只读且非 arm64） - 检查
which python3：正确路径应为/opt/homebrew/bin/python3或~/miniforge3/bin/python3，而非/usr/local/bin/python3
推荐两种可靠安装方式：Homebrew 或 Miniforge
二者都默认提供 arm64 二进制，但适用场景不同：
立即学习“Python免费学习笔记（深入）”；
-
Homebrew（适合轻量开发/脚本/工具链）：
确保已装 Apple Silicon 版 Homebrew（路径为/opt/homebrew），再执行：brew install python
验证：python3 -c "import sys; print(sys.base_prefix)"应输出/opt/homebrew/opt/python@3.x/Frameworks/Python.framework/Versions/3.x -
Miniforge（适合数据科学/深度学习）：
它专为 conda-forge + arm64 设计，避免 solver 卡死：curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh"bash Miniforge3-MacOSX-arm64.sh
安装后运行conda info --subdir，输出必须是osx-arm64
避开 pyenv 和旧版 Conda 的典型陷阱
pyenv 在 M1/M2 上默认不启用 universal2 编译，容易产出 x86_64 解释器；Anaconda 官方包仍以 osx-64 为主，极易触发 solver 爆炸或降级到 Intel 版本。
- 如果你之前用过
pyenv，先清理：rm -rf ~/.pyenv，再重装（如坚持要用，必须加CONFIGURE_OPTS="--enable-universal2" pyenv install 3.11.9） - 彻底卸载 Anaconda：
brew uninstall --cask anaconda，不要试图用conda config --add channels conda-forge补救，默认 channel 已污染 solver 状态 - 升级 pip 必须用：
python3 -m pip install -U pip，直接调用pip install -U pip可能命中缓存的 x86_64 pip 二进制
IDE 和虚拟环境必须指向 arm64 解释器路径
VS Code、PyCharm 等会自动扫描 PATH，但常误选 /usr/bin/python3 或 Rosetta 启动的旧解释器。
- 在 VS Code 中按
Cmd+Shift+P→ 输入 “Python: Select Interpreter”，手动选择路径含/opt/homebrew/或miniforge3/的项 - 创建 venv 时显式指定解释器：
python3 -m venv myenv（前提是python3是 arm64） - 检查 venv 内解释器架构：
myenv/bin/python -c "import platform; print(platform.machine())"—— 必须仍是arm64，否则说明 base 解释器不干净
最易被忽略的一点：PATH 中 /opt/homebrew/bin 或 ~/miniforge3/bin 必须排在 /usr/bin 和 /usr/local/bin 之前，否则 which python3 仍可能返回错误路径。检查 echo $PATH，必要时在 ~/.zshrc 中前置 export。
