如何使用mamba安装Uber的h3-py？M1 Mac安装报错问题排查

环境信息 #

• 设备：MacBook Pro M1 Max
• Python环境管理：Miniforge3，已将默认包管理工具切换为mamba

故障复现 #

尝试在虚拟环境中安装Uber开源的H3地理网格库Python版本，先后尝试4种安装方式全部失败：

• 执行mamba install h3-py，依赖求解阶段报错：

encountered problems while solving:
- nothing provides requested h3-py

• 切换conda执行conda install h3-py，返回渠道无对应包报错：

PackagesNotFoundError: The following packages are not available from current channels:

  - h3-py

Current channels:

  - https://conda.anaconda.org/conda-forge/osx-arm64
  - https://conda.anaconda.org/conda-forge/noarch
  - https://repo.anaconda.com/pkgs/main/osx-arm64
  - https://repo.anaconda.com/pkgs/main/noarch
  - https://repo.anaconda.com/pkgs/r/osx-arm64
  - https://repo.anaconda.com/pkgs/r/noarch

• 安装命令追加-c conda-forge参数强制指定conda-forge源，仍返回相同报错（conda-forge本身就是当前环境配置的默认主通道，参数未产生实际效果）
• 执行pip install h3-py，返回无匹配发行版报错：

ERROR: Could not find a version that satisfies the requirement h3-py (from versions: none)
ERROR: No matching distribution found for h3-py

临时解决方式与遗留疑问 #

最终通过执行pip install h3完成了库的安装，但存在两点疑问：

1. 此前未使用mamba的Python环境中曾成功安装h3、h3pandas，为什么当前环境完全检索不到h3-py？
2. 官方安装文档明确标注h3-py可通过conda-forge渠道安装，为什么指定conda-forge源依然找不到包？

根本原因 #

故障由包名混淆、架构适配差异、文档更新滞后三个因素共同导致：

• 包名认知错误：h3-py只是H3 Python绑定的GitHub源码仓库名，PyPI源从未发布过名为h3-py的包；conda-forge源上的h3-py也只是3.0版本之前的旧命名，4.0及之后的版本全渠道统一使用h3作为正式发布包名，你之前在其他环境安装成功的也是h3包，并非h3-py。
• 架构适配缺失：conda-forge上历史发布的所有h3-py旧包，从未提供过osx-arm64（Apple M系列芯片原生架构）的构建版本，仅支持x86_64架构。你当前安装的Miniforge3是arm64原生版本，mamba/conda检索安装包时只会匹配osx-arm64、noarch架构的资源，自然找不到仅存在x86构建的h3-py旧包。此前其他环境能安装成功，基本都是因为旧环境运行在Rosetta 2转译的x86_64模式下，可以匹配到对应架构的旧版包。
• 文档更新滞后：官方安装文档提到的conda-forge安装渠道实际针对的是新版h3包，标注h3-py属于旧内容未及时更新的遗留问题。

标准安装方案 #

不管使用mamba、conda还是pip，直接安装h3即可获得完整的H3 Python绑定功能，对应命令如下：

• mamba安装：mamba install h3
• conda安装：conda install h3
• pip安装：pip install h3

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