tensorflow-macos 和 tensorflow-metal 必须成对安装且版本严格匹配，如2.18.1与1.2.0；需使用 arm64 架构 python（3.9–3.12），禁用 rosetta，推荐 conda 指定 osx-arm64 创建环境并用 pip 精确安装二者。
tensorflow-macos 和 tensorflow-metal 必须成对安装，缺一不可；单独装 tensorflow（官方 PyPI 版）在 M2 上会直接报 Illegal instruction: 4 或根本找不到匹配版本。
确认 Python 环境架构与版本
Apple Silicon（M2）只支持 arm64 架构的 Python，且 tensorflow-macos 官方 wheel 仅兼容 Python 3.9–3.12。常见坑是：用 Rosetta 启动的 Terminal 运行 python，结果 platform.machine() 返回 x86_64，后续所有包都会装错。
- 运行
python -c "import platform; print(platform.machine(), platform.platform())"，输出必须含arm64和macOS-XX.X-arm64 - 如果显示
x86_64或10.16，说明你正在 Rosetta 模式下运行 —— 退出 Terminal，右键 → “显示简介” → 取消勾选“使用 Rosetta”，重启 Terminal - 推荐用
pyenv或 Miniconda 的osx-arm64channel 创建环境，避免系统 Python 干扰
用 conda 创建干净的 arm64 环境
conda 在 Apple Silicon 上比 pip 更稳定，尤其对 numpy、scipy 等底层依赖的 ABI 兼容性处理更好。关键是要强制指定 osx-arm64 子目录。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 执行
CONDA_SUBDIR=osx-arm64 conda create -n tf218 python=3.12 -c conda-forge -y - 激活后先升级 pip：
conda activate tf218 && python -m pip install --upgrade pip - 不要用
conda install tensorflow—— 官方 conda channel 不提供 Metal 插件，只会装 x86 兼容版，GPU 识别失败
安装 tensorflow-macos + tensorflow-metal 的精确版本组合
版本不匹配是 GPU 不生效的最常见原因。截至 2026 年 7 月，tensorflow-macos 2.18.1 + tensorflow-metal 1.2.0 是唯一经过大规模验证的稳定组合；更高版本（如 2.19+）尚未发布适配 Metal 的 wheel。
- 运行
pip install tensorflow==2.18.1 tensorflow-metal==1.2.0 -i https://pypi.doubanio.com/simple/（豆瓣源在国内更稳） - 避免混用
tensorflow-macos和tensorflow—— 二者冲突，pip show tensorflow应显示Version: 2.18.1，而非tensorflow-macos - 若提示
No matching distribution found for tensorflow-metal，检查是否漏设CONDA_SUBDIR或 pip 使用了错误 Python 解释器（用which python确认路径）
验证 GPU 是否真正启用
tf.config.list_physical_devices('GPU') 返回非空列表 ≠ 实际加速生效。Metal 后端只加速部分算子（如卷积、矩阵乘），且对 float64、复数类型完全不支持 —— 这类操作会自动回退到 CPU，但不会报错。
- 运行
python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"，应输出类似[PhysicalDevice(name='/physical_device:GPU:0', device_type='GPU')] - 进一步验证加速效果：跑一个最小训练循环，监控活动监视器里的 GPU 使用率（不是“GPU 能量”条）
- 注意
tf.test.is_gpu_available()已弃用，返回True也不代表 Metal 在工作；以list_physical_devices和实际训练耗时为准
tensorflow-metal 当前只支持 float32 和 int32，模型里一旦出现 tf.complex64 或 tf.float64 张量，对应层会静默降级到 CPU，整个 batch 的加速就断掉了。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
