安装realcugan-ncnn-vulkan-python失败 无法构建wheel报错求助

问题场景 #

安装realcugan-ncnn-vulkan-python模块时触发编译报错，核心错误日志如下：

raise CalledProcessError(retcode, cmd)
      subprocess.CalledProcessError: Command '['cmake', '-S', '/private/var/folders/p9/mx7w4h2149vdglfr2c0ddmpm0000gn/T/pip-install-p6r_9mxi/realcugan-ncnn-vulkan-python_71a0be6d527745c59fa316681cfad201/realcugan_ncnn_vulkan_python', '-B', '/private/var/folders/p9/mx7w4h2149vdglfr2c0ddmpm0000gn/T/pip-install-p6r_9mxi/realcugan-ncnn-vulkan-python_71a0be6d527745c59fa316681cfad201/build/temp.macosx-10.9-x86_64-cpython-39_realcugan-ncnn-vulkan-python', '-GNinja', '-DCMAKE_BUILD_TYPE=Release', '-DCMAKE_INSTALL_PREFIX:PATH=/private/var/folders/p9/mx7w4h2149vdglfr2c0ddmpm0000gn/T/pip-install-p6r_9mxi/realcugan-ncnn-vulkan-python_71a0be6d527745c59fa316681cfad201/build/lib.macosx-10.9-x86_64-cpython-39/realcugan_ncnn_vulkan_python', '-DCMAKE_MAKE_PROGRAM=/private/var/folders/p9/mx7w4h2149vdglfr2c0ddmpm0000gn/T/pip-build-env-vfonxjmm/overlay/bin/ninja', '-DBUILD_SHARED_LIBS:BOOL=OFF', '-DCALL_FROM_SETUP_PY:BOOL=ON']' returned non-zero exit status 1.
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for realcugan-ncnn-vulkan-python
Failed to build realcugan-ncnn-vulkan-python
ERROR: Could not build wheels for realcugan-ncnn-vulkan-python, which is required to install pyproject.toml-based projects

故障原因 #

该报错本质是cmake配置环节执行失败，最终导致wheel包构建不成功，常见原因有三类：

• 本地缺少编译必须的系统依赖：这个模块依赖cmake、ninja做构建，还需要Vulkan SDK、Xcode命令行工具提供基础编译环境，少任何一个依赖都会让cmake直接退出，返回状态码1
• 当前环境没有匹配的预编译wheel包：从日志路径看使用的是macOS x86_64架构的Python3.9，这个组合没有现成的预编译安装包，pip会自动走本地源码编译流程，只要本地编译环境有一点问题就会安装失败
• 目前贴出的日志只是pip捕获的外层报错，没有打印cmake运行时的具体错误（比如找不到头文件、路径检测失败、依赖拉取失败这类具体问题），没法直接定位到唯一的故障点

解决方法 #

按优先级从高到低尝试以下方案：

• 优先绕开本地编译流程
  先执行pip install --upgrade pip setuptools wheel把pip相关组件升级到最新版本，再重新执行安装命令。新版pip会自动匹配适配当前系统和Python版本的预编译wheel，不需要本地编译即可完成安装。如果仍触发编译，可以切换到Python3.10或者3.11版本，这两个版本的预编译包覆盖更完善，基本不会触发本地编译。
• 补全本地编译需要的依赖
  执行xcode-select --install安装Xcode命令行编译工具；已安装homebrew的话执行brew install cmake ninja安装所需的构建工具；再安装对应macOS版本的Vulkan SDK，确认系统能正常识别Vulkan库路径之后再重新尝试安装。
• 定位cmake的具体错误
  以上两个方法都无效的话，可以手动下载对应版本的模块源码，在源码目录手动执行日志中打印的那条cmake配置命令，就能看到cmake输出的具体报错，比如缺哪个依赖、哪个版本不兼容之类的，针对性修复即可。

补充：日志里的构建目标是macOS 10.9，属于比较老的系统版本，如果你的系统版本较新，也可能出现构建目标和当前系统SDK不兼容的问题，安装时可以通过环境变量指定当前系统的macOS SDK版本再尝试编译。

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