Ubuntu 安装 PyCINRAD（cinrad）踩坑记录

Ubuntu 安装 PyCINRAD（cinrad）踩坑记录：从 numpy 报错到 gcc 缺失，再到 NumPy 2.x 兼容问题解决

前言

最近在做雷达火灾烟羽识别相关开发，准备用国产 Python 雷达处理库PyCINRAD。
安装包名是：

pipinstallcinrad

结果安装过程连续踩坑，前后遇到了 3 个问题：

1. ModuleNotFoundError: No module named 'numpy'
2. gcc failed: No such file or directory
3. PyArray_Descr has no member named 'subarray'

最后总算装好了，这里把整个排障过程整理出来，给后面需要在Ubuntu + Conda + Python 3.10环境安装cinrad的朋友做个参考。

一、环境说明

我的环境大致如下：

• Ubuntu / Linux
• Conda 虚拟环境
• Python 3.10
• 目标安装包：cinrad

官方安装文档里提到，PyCINRAD 要先安装一些依赖，比如cartopy、matplotlib、numpy、cython，然后再安装cinrad。(pycinrad.cn)

二、第一个坑：明明装了 numpy，还是提示No module named 'numpy'

1. 现象

我先装了numpy：

pipinstallnumpy

安装成功后，再执行：

pipinstallcinrad

结果报错：

ModuleNotFoundError: No module named 'numpy'

2. 原因

这里不是当前环境真的没装numpy，而是pip 在构建 wheel 时启用了隔离构建环境。

也就是说：

• 你当前 Conda 环境里有numpy
• 但是pip install cinrad时，会临时新建一个干净的构建环境
• 这个临时环境里没有numpy
• 而cinrad的构建脚本又提前import numpy
• 所以直接报错

3. 解决办法

关闭构建隔离，直接让它使用当前环境里的依赖：

pipinstallcinrad --no-build-isolation

不过这一步只是解决了第一个问题，后面还会继续暴露新的坑。

三、第二个坑：缺少 gcc 编译器

1. 现象

继续安装后，报错变成了：

error: command 'gcc' failed: No such file or directory

从日志可以看到，安装过程已经进入了 C 扩展编译阶段，正在编译cinrad._utils扩展，但系统里没有gcc。

2. 原因

cinrad不是纯 Python 包，它包含本地 C 扩展。
所以安装时需要系统里有 C 编译器。

3. 解决办法

在 Ubuntu / Debian 下安装基础编译工具链：

sudoaptupdatesudoaptinstall-ybuild-essential

安装完成后，再重新执行：

pipinstallcinrad --no-build-isolation

这时候gcc问题就解决了。

四、第三个坑：NumPy 2.x 编译兼容问题

1. 现象

装完gcc后，安装仍然失败，但这次报错变成了：

error: ‘PyArray_Descr’ {aka ‘struct _PyArray_Descr’} has no member named ‘subarray’

并且日志里还能看到编译时引用的是当前环境中的 NumPy 头文件。

2. 原因

这一步说明：

• 编译器已经没问题了
• 真正卡住的是cinrad和当前 NumPy 版本的 C API 不兼容

我一开始装的是较新的numpy 2.2.6，而 NumPy 2.x 本身是一次大版本升级，官方就明确说明过带来了breaking changes，尤其是C API / ABI兼容性变化。(numpy.org)

对于一些还没完全适配 NumPy 2.x 的老项目，在编译 C 扩展时就很容易出这种错。

3. 解决办法

把 NumPy 降级到 1.26.4，并顺手把 Cython 也压到 3 以下：

pip uninstall-ycinrad numpy pip cache purge pipinstall"numpy==1.26.4""cython<3"setuptools wheel pipinstallcinrad --no-build-isolation --no-cache-dir

之所以选numpy==1.26.4，原因是：

• 支持 Python 3.10。(pypi.org)
• 属于 NumPy 1.x 比较稳定的版本
• 对这类老的 C 扩展项目兼容性通常更好

五、最终可用的完整安装方案

如果你也是在Ubuntu + Conda + Python 3.10环境下装cinrad，建议直接按下面这套命令走：

pip uninstall-ycinrad numpy pip cache purge pipinstall"numpy==1.26.4""cython<3"setuptools wheelsudoaptupdatesudoaptinstall-ybuild-essential pipinstallcinrad --no-build-isolation --no-cache-dir

六、如果当前环境已经装乱了，建议直接新建环境

如果前面已经来回折腾很多次，最省事的方法反而是重新建一个干净环境：

conda create-ncinrad310python=3.10-yconda activate cinrad310 pipinstall"numpy==1.26.4""cython<3"setuptools wheelsudoaptupdatesudoaptinstall-ybuild-essential pipinstallcinrad --no-build-isolation --no-cache-dir

七、这次踩坑的本质总结

这次安装失败，实际上不是一个问题，而是连续踩了三个坑：

问题 1：构建隔离环境里没有 numpy

报错：

ModuleNotFoundError: No module named 'numpy'

问题 2：系统没有 gcc

报错：

error: command 'gcc' failed: No such file or directory

日志里明确显示，编译cinrad._utils时调用 GCC 失败。

问题 3：NumPy 2.x 和 cinrad 当前编译链不兼容

报错：

PyArray_Descr has no member named 'subarray'

这是进入 C 扩展编译后，由 NumPy C API 兼容问题引发的。

八、注意：有些警告不是主因

安装日志里还会看到类似下面的警告：

Package 'cinrad.data' is absent from the `packages` configuration Package 'cinrad.data.colormap' is absent from the `packages` configuration

这些是setuptools的打包警告，不是本次安装失败的根本原因。
真正导致安装失败的，是：

• numpy构建隔离问题
• 系统缺gcc
• NumPy 2.x 编译兼容问题

从最终中断日志就能看出来，失败点很明确。

九、一句话结论

如果你在 Linux 下安装cinrad遇到各种报错，最稳的方案就是：

固定numpy==1.26.4，安装build-essential，并使用--no-build-isolation安装。

直接用这套：

pip uninstall-ycinrad numpy pip cache purge pipinstall"numpy==1.26.4""cython<3"setuptools wheelsudoaptupdatesudoaptinstall-ybuild-essential pipinstallcinrad --no-build-isolation --no-cache-dir

十、附：我这次最终解决问题的核心思路

不是“看到一个报错就只修一个”，而是分层排查：

• 先解决 Python 构建依赖问题
• 再解决系统编译环境问题
• 最后解决 NumPy 版本兼容问题