Numba 0.64.0 版本解析:NumPy 2.4 支持、np.moveaxis 新增与关键 Bug 修复详解
Numba 0.64.0 版本解析:NumPy 2.4 支持、np.moveaxis 新增与关键 Bug 修复详解
Numba 0.64.0 是一个重要的主版本发布,核心亮点是正式支持 NumPy 2.4,同时新增了对 np.moveaxis 的 nopython 模式支持,并修复了 np.all / np.any 标量处理、数组布局转换 readonly 处理、s390x 整数类型提升、Python 3.11 大整数幂运算精度等一系列问题。本文以官方发布说明(docs/source/release/0.64.0-notes.rst)为骨架,结合仓库源码与测试用例,逐项剖析这些变更的实现原理与迁移影响,帮助读者在升级到 0.64.0 时顺利完成 NumPy 兼容性切换并规避潜在陷阱。
版本概览与兼容性声明
Numba 0.64.0 发布于 2026 年 2 月 18 日,属于主版本(major release)发布。发布说明开篇即点明本版本的核心能力变化:
Numba now supports NumPy 2.4.
这一定位意味着:使用 0.64.0 的开发者可以在已经升级到 NumPy 2.4 的 Python 环境中继续使用 Numba 的 nopython 模式对数组操作进行 JIT 编译,而无需回退 NumPy 版本。与 NumPy 支持同步推进的还有对 Python 3.14 的持续适配(见 PR #10256、#10339 的 CI/依赖更新),以及 CI 从 Azure 向 GitHub Actions 迁移、osx-64 被列入 Tier 2 支持列表等工程化调整(PR #10347、#10384)。
从发布说明的 PR 列表看,0.64.0 汇聚了来自社区十余名贡献者的约 30 个合并请求,内容涵盖 NumPy 兼容、新功能、缺陷修复、CI/文档维护四大类。本文聚焦其中的功能性变更,逐个展开源码级分析。
NumPy 2.4 支持:两个必须注意的 API 移除
NumPy 2.4 对 Numba 最直接的影响是移除了两个旧 API,若代码中仍在调用它们,升级后会在 nopython 模式下直接报错。官方建议如下:
np.trapz 已被移除,改用 np.trapezoid
- NumPy 2.4 中
np.trapz被彻底移除; - 替代方案是
np.trapezoid,该函数自 NumPy 2.0 起即已可用; - 迁移时只需将调用名从
np.trapz替换为np.trapezoid,参数签名(y、x、dx、axis)保持一致。
np.in1d 已被移除,改用 np.isin
- NumPy 2.4 中
np.in1d被彻底移除; - 替代方案是
np.isin,语义等价:判断第一个数组中的元素是否出现在第二个数组中; - 迁移时替换函数名即可,
np.isin同样支持assume_unique、invert等参数。
这两项调整的落地由 PR #10393(add Numpy 2.4 support)完成,并配套 PR #10417(Fix: NumPy2.4 CI test error)修复了 CI 中的兼容性测试问题。对于 Numba 使用者来说,这是升级 0.64.0 时最需要主动执行的代码迁移动作——因为 Numba 的 nopython 模式并不拦截对已移除 API 的调用,错误会以 TypingError 或运行时错误的形式暴露出来,提前替换更稳妥。
新功能:np.moveaxis 的 nopython 模式支持
np.moveaxis 是 NumPy 中用于将数组的轴移动到新位置的高频函数,常用于维度重排。此前 Numba 的 nopython 模式并不支持它,0.64.0 通过 PR #10366 补齐了这一能力。
实现原理:基于 transpose 的轴重排
Numba 对 np.moveaxis 的实现位于 numba/np/arrayobj.py,通过 @overload(np.moveaxis) 注册:
@overload(np.moveaxis)
def numpy_moveaxis(a, source, destination):
if not isinstance(a, types.Array):
raise errors.TypingError('The first argument "a" must be an array')
...
def impl(a, source, destination):
source = normalize_axis_tuple("np.moveaxis", "source", ndim, source)
destination = normalize_axis_tuple("np.moveaxis", "destination", ndim, destination)
if len(source) != len(destination):
raise ValueError(...)
order_list = [n for n in range(a.ndim) if n not in source]
for dest, src in sorted(zip(destination, source)):
order_list.insert(dest, src)
order = order_init
for i, o in enumerate(order_list):
order = tuple_setitem(order, i, o)
return a.transpose(order)
return impl
从源码结构可以清晰地看出其设计思路:np.moveaxis 在 Numba 中不是独立实现的高维搬移逻辑,而是先计算一个轴置换顺序(order),再复用底层已经高度优化的 a.transpose(order)。这既避免了重复实现内存搬移逻辑,又保证了与 NumPy 语义的一致性——np.moveaxis 本身在 NumPy 中的实现也是基于转置的视图操作,不复制数据。
类型检查方面,实现严格约束了三类参数:
| 参数 | 允许类型 | 非法输入时的报错信息 |
|---|---|---|
a |
数组(types.Array) |
The first argument "a" must be an array |
source |
整数或整数序列(types.Integer / types.Sequence) |
The second argument "source" must be an integer or sequence of integers |
destination |
整数或整数序列(types.Integer / types.Sequence) |
The third argument "destination" must be an integer or sequence of integers |
支持负数轴索引与元组形式的 source/destination,与 NumPy 行为对齐。
测试覆盖:边界条件与异常路径
测试位于 numba/tests/test_np_functions.py,分为功能与异常两组:
功能测试(test_moveaxis_basic) 使用 np.arange(120).reshape(1, 2, 3, 4, 5) 这一 5 维数组,覆盖了多组 source/destination 组合:
for source, destination in (
(0, -1), # 负轴索引
(1, 3), # 单轴移动
((0, 1), (-1, -2)), # 多轴 + 负索引
((0, 1), (-2, -1)), # 多轴顺序交换
((1, -3), (-2, 4)), # 混合正负索引
):
expected = pyfunc(a, source, destination)
got = cfunc(a, source, destination)
self.assertPreciseEqual(expected, got)
每组结果都与纯 Python 版 NumPy 调用做 assertPreciseEqual 精确比对,验证 nopython 编译结果与 NumPy 语义完全一致。
异常测试(test_moveaxis_exception) 则验证了四条错误路径:
- 非数组输入、非整数 source/destination 触发
TypingError,并断言了对应的报错文案; cfunc(np.arange(4), 1, 0)触发ValueError: np.moveaxis: Argument source out of bounds;(0, 1) -> (1, -3)触发np.moveaxis: Argument destination out of bounds;(0, 0)重复轴触发np.moveaxis: repeated axis in source argument;(0, 1) -> (1, -1)触发np.moveaxis: repeated axis in destination argument。
这些测试一方面保证了实现的正确性,另一方面也表明越界与重复轴的报错文案与 NumPy 保持一致,便于开发者排错。
使用示例
import numpy as np
from numba import njit
@njit
def shift_axis(a):
# 将第 0 轴移动到最后一维
return np.moveaxis(a, 0, -1)
a = np.arange(24).reshape(2, 3, 4)
print(shift_axis(a).shape) # (3, 4, 2)
Bug 修复详解
0.64.0 共修复了五类功能性缺陷,其中多数影响面较大,值得逐一关注。
np.all 与 np.any 的标量输入处理
问题背景:在 0.64.0 之前,np.all 和 np.any 在 nopython 模式下被传入标量(如 np.all(5)、np.any(0))时会失败。这是因为此前的 overload 实现只考虑了数组输入,标量路径缺失。
修复内容(PR #10223、#10224):以 np.all 为例,修复后的实现在 numba/np/arraymath.py 中为标量增加了独立分支:
@overload(np.all)
@overload_method(types.Array, "all")
def np_all(a):
# for scalar
if isinstance(a, (types.Number, types.Boolean)):
def scalar_all(a):
return bool(a)
return scalar_all
if isinstance(a, (NPDatetime, NPTimedelta)):
def temporal_scalar_all(a):
return np.int64(a) != 0
return temporal_scalar_all
# for array
if isinstance(a, types.Array):
def flat_all(a):
for v in np.nditer(a):
if not v.item():
return False
return True
return flat_all
return None
np.any 的修复(PR #10224)与之对称,同样增加了标量分支,将标量转换为布尔值。从源码看,该 overload 同时服务于 np.all 函数与数组方法 .all()(通过 @overload_method 注册),因此这一修复对两种调用形式都生效。
修复后的行为语义为:
- 标量输入:
np.all(x)等价于bool(x),np.any(x)同样等价于bool(x)(对NPDatetime/NPTimedelta则比较其int64表示是否为 0); - 数组输入:维持原有逻辑,遍历所有元素判断是否全真/存在真值。
np.asfortranarray / np.ascontiguousarray 的 readonly 处理
问题背景(对应 issue #10357):此前当输入数组是只读(readonly)时,即使通过 np.asfortranarray 或 np.ascontiguousarray 产生了新的拷贝,返回的数组仍然继承 readonly 标志。这与 NumPy 语义不符——拷贝理应产生可写的新数组。
修复内容(PR #10390):核心修改在 numba/np/arrayobj.py 的 _as_layout_array 与新增的 _as_layout_array_intrinsic 中。布局转换的内在逻辑是:
- 0 维输入:
asfortranarray()返回 1 维数组(shape 为(1,)); - 输入布局与目标布局一致(或 1 维且为 C/F 任一连续布局):直接返回原数组(借用,不拷贝);
- 输入布局未知(
layout == 'A'):编译期无法确定,运行时用is_contiguous/is_fortran检查,已连续则直接返回,否则拷贝; - 其余情况:拷贝为指定布局的新数组。
修复的关键在于拷贝路径:新增的 intrinsic _as_layout_array_intrinsic 在构造返回类型时显式指定:
ret = a.copy(
layout=output_layout.literal_value,
ndim=max(a.ndim, 1),
readonly=False) # 拷贝结果必须是可写的
即:凡是通过拷贝得到的新数组,其 readonly 一律置为 False;而直接借用原数组的路径(布局已匹配)则保留原数组的属性。这样既符合 NumPy 语义(拷贝产生可写数组),又避免了不必要的拷贝开销。
两个 overload 的完整行为:
np.ascontiguousarray(a):标量/布尔输入先np.array(a)再转 C 连续布局;数组输入走_as_layout_array_intrinsic(a, 'C');np.asfortranarray(a):标量/布尔输入先np.array(a)再转 Fortran 连续布局;数组输入走_as_layout_array_intrinsic(a, 'F')。
同时 _as_layout_array 中明确断言返回类型布局与目标布局一致(assert retty.layout == output_layout),保证编译期类型与运行时行为相符。
s390x 上整数类型提升(SystemZ ABI 兼容)
问题背景:在 s390x(IBM Z)架构上,pythonapi 相关路径存在段错误(segmentation fault)。根因是 SystemZ ABI 要求整数参数在传入函数时须提升到完整的寄存器宽度,而 Numba 在 CPU 与 Python API 的 lowering 层没有执行这一提升。
修复内容(PR #10396):在 CPU 与 Python API 的 lowering 层为整数类型补充了完整的寄存器宽度提升逻辑,确保在 s390x 上按 ABI 规范传递整数。这一修复对大多数 x86/ARM 用户无感知,但对 IBM Z 上的部署而言是关键的正确性补丁。
Python 3.11 大整数幂运算精度丢失
问题背景(对应 issue #9931):在 Python 3.11 上,nopython 模式中执行整数幂运算(如 x ** 2)时,当结果大于 2^53 会出现精度丢失。2^53 正是 IEEE 754 double 可以无损表示的最大整数,说明幂运算路径中存在隐式的浮点转换。
修复内容(PR #10398):修复后,整数幂运算在结果大于 2^53 时仍保持完整整数精度。此修复针对 Python 3.11 生效,修复后的行为可验证如下:
import numpy as np
from numba import njit
@njit
def power2(x):
return x ** 2
# 2^53 之上,必须保持精确整数结果
x = 2**27 + 1 # 大于 2^53 开方后的整数
print(power2(x)) # 结果不再丢失精度
print(power2(x) == (2**27 + 1) ** 2) # True
对于依赖大整数精确运算的数值代码,这一修复避免了静默的精度污染。
工程与 CI 层面的变更
发布说明的 PR 列表中还包含若干不直接改变用户可见功能、但对项目演进有意义的工程调整,简述如下:
- CI 迁移与清理:将 osx64 相关的 Azure 流水线移除并迁移至 GitHub Actions(PR
#10347),删除 pre-commit 配置(PR#10351),新增 numba 定时测试工作流(PR#10324); - 依赖与工具链升级:Python 依赖版本提升至 3.14(PR
#10339),wheel 构建工作流改为安装预发布的 llvmlite 版本(PR#10391),并对 conda-libmamba-solver 添加版本约束(PR#10359); - 版本支持表更新:为 0.64.0rc1 及正式版更新版本支持矩阵(PR
#10422、#10438),并将 osx-64 加入 Tier 2 支持列表(PR#10384); - 文档修正:修正 macOS 上 OpenMP 依赖说明与正文不一致的问题(PR
#10369); - 0.63.x 补丁回移:将 0.63.0 与 0.63.1 的修复 cherry-pick 进入本版本线(PR
#10371、#10378)。
升级到 0.64.0 的行动清单
结合发布说明与源码分析,从 0.63.x 升级到 0.64.0 时建议按以下顺序核对:
- NumPy 版本:确认环境中的 NumPy 已升级到 2.4(本版本的核心能力);
- API 迁移:全局搜索并替换
np.trapz→np.trapezoid、np.in1d→np.isin; - 标量断言:如代码中大量使用
np.all(...)/np.any(...)且可能传入标量,0.64.0 后行为与 NumPy 对齐(标量转 bool),可放心移除以往的规避写法; - 布局转换:如依赖
np.asfortranarray/np.ascontiguousarray的结果可写性,0.64.0 的拷贝路径已保证返回可写数组; - 平台验证:若在 s390x(IBM Z)部署,务必升级以修复 pythonapi 段错误;若在 Python 3.11 上做超大整数幂运算,升级后可获得完整精度;
- 新能力:
np.moveaxis现在可直接在@njit函数中使用,替代手动 transpose 的繁琐写法。
关键源码与测试索引
- 发布说明原文:docs/source/release/0.64.0-notes.rst
np.moveaxisoverload 实现:numba/np/arrayobj.pynp.moveaxis功能/异常测试:numba/tests/test_np_functions.pynp.all标量修复实现:numba/np/arraymath.pynp.ascontiguousarray/np.asfortranarray布局转换与 readonly 修复:numba/np/arrayobj.py- NumPy 兼容性文档:docs/source/reference/numpysupported.rst
- 版本支持矩阵与发布流程相关:
docs/source/release/0.64.0-notes.rst中 PR#10422、#10438对应的更新