如何构建独立于macOS版本的Python Wheel包？

1. 基于最低兼容macOS版本构建 #

• 构建时指定你需要支持的最低macOS版本（比如macOS 10.15），生成的Wheel包会带有该版本标识，同时能在所有更高版本的macOS上运行。
• 操作方式：构建前设置环境变量MACOSX_DEPLOYMENT_TARGET，示例命令：

  export MACOSX_DEPLOYMENT_TARGET=10.15
  # 用setup.py构建
  python setup.py bdist_wheel
  # 或者用build模块
  python -m build --wheel
  

• 最终生成的Wheel包类似mylib-16.2.0-cp39-cp39-macosx_10_15_arm64.whl，能被10.15及以上版本的macOS用户通过pip正常安装。

2. 构建Universal2架构Wheel #

• 如果需要同时覆盖Mac x86和ARM平台，可以构建Universal2 Wheel，它包含两种架构的二进制文件，文件名带有universal2标识，比如mylib-16.2.0-cp39-cp39-macosx_10_15_universal2.whl。
• 构建时同样需要设置MACOSX_DEPLOYMENT_TARGET，并且确保构建环境支持生成Universal2二进制（通常在ARM Mac上用Xcode工具链即可实现，也可通过交叉编译完成）。

3. 用工具调整Wheel平台标签 #

• 对于已构建好的Wheel包，可以用工具修改其平台标签，扩大兼容的macOS版本范围：
  • 纯Python Wheel（无二进制扩展）：可以直接修改包内的WHEEL文件标签，或用wheel工具重新打标签：

    wheel tags --remove-tag macosx_14_0_arm64 --add-tag macosx_10_15_arm64 mylib-16.2.0-cp39-cp39-macosx_14_0_arm64.whl
    

  • 含二进制扩展的Wheel：推荐用reprocwheel工具处理，它会自动调整兼容版本标签，同时确保二进制能在目标版本正常运行：

    reprocwheel --platform macosx_10_15_arm64 mylib-16.2.0-cp39-cp39-macosx_14_0_arm64.whl
    

关键提醒 #

• 不要只改Wheel文件名，pip会同时检查文件名和包内WHEEL文件的标签信息，仅改文件名可能导致安装后运行异常。
• 确保二进制扩展在最低目标macOS版本上能正常工作，避免使用高版本系统独有的API。

内容的提问来源于stack exchange，提问作者stefanbschneider