Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

NumPy 2: Module Compiled Against API Version 0x10

NumPy 2 changed its C ABI, so extensions built against 1.x headers cannot resolve _ARRAY_API. Rebuild, upgrade the wheel, or pin numpy<2 as a stopgap.

~4 min readPython
#Python#NumPy#Packaging#Debugging
3D illustration of an array grid plate with a broken connector beside a rebuild wrench

Introduction & Quick Summary

Symptom. After installing NumPy 2, importing pandas, scikit-learn, a compiled ML package or your own C extension prints a long warning beginning A module that was compiled using NumPy 1.x cannot be run in NumPy 2.2.6 as it may crash. and then fails with AttributeError: _ARRAY_API not found or ImportError: numpy.core.multiarray failed to import. NumPy itself imports fine; the failure comes from the extension compiled against the older headers.

Cause. NumPy 2.0 changed its C ABI. Extensions built against NumPy 1.x headers store pointers to a symbol table whose layout changed, so the loader cannot resolve _ARRAY_API and the import aborts. Wheels built with numpy<2 in their build environment are the usual trigger, because pip happily installs them next to NumPy 2 — the dependency metadata does not express an ABI requirement.

Fix. Upgrade the affected extension to a wheel built against NumPy 2 (pybind11 2.12+ or NumPy-2 headers), rebuild it from source in an isolated environment, or pin numpy<2 for the whole environment as a stopgap. pip check will not find this; the version pair has to be inspected directly.

Core Mechanics, Signatures & Reproducible Setup

The mechanism is a compiled extension resolving a C symbol table at import time:

python
# The pattern behind every message: extension imports, then asks for the API table import numpy as np print(np.__version__) # 2.2.6 import <extension> # AttributeError: _ARRAY_API not found

A minimal reproducer without third-party packages, using an older wheel from the cache:

bash
python -m venv /tmp/np2 && . /tmp/np2/bin/activate pip install "numpy==2.2.6" pip install --only-binary :all: "pandas==2.1.4" # wheel built against numpy 1.x python -c "import pandas" # numpy.core.multiarray failed to import

The stopgap, which pins the environment back to the ABI the extensions were built for:

bash
pip install "numpy<2" python -c "import numpy, pandas; print(numpy.__version__, pandas.__version__)"

The durable fix, which asks the build system for the new headers and rebuilds against them:

bash
pip install --upgrade --force-reinstall --no-cache-dir "pandas>=2.2.3" # compiled extensions of your own: pip install --no-build-isolation --force-reinstall .

Key Comparison Table

The message your environment shows, and what it points at:

MessageWhere it comes fromFix
A module that was compiled using NumPy 1.x cannot be run in NumPy 2.xNumPy 2 import hookUpgrade or rebuild the extension
AttributeError: _ARRAY_API not foundExtension bodySame
ImportError: numpy.core.multiarray failed to importDependent librarySame
ModuleNotFoundError: No module named 'numpy.core'Library importing a private pathLibrary upgrade (numpy._core is private)
RuntimeError: Numpy is not availabletorch/torchvision version mismatchUpgrade the torch pair
AttributeError: np.float_ was removedApplication code using removed aliasesUse np.float64

The removals that break day-two code after the upgrade:

Removed in NumPy 2ReplacementNote
np.float_np.float64Alias removed, same type
np.complex_np.complex128
np.unicode_np.str_
np.string_np.bytes_
np.NaN, np.Inf, np.inftynp.nan, np.infConstants removed
np.matnp.asmatrixMatrix subclass discouraged
np.alltrue, np.sometruenp.all, np.any
numpy.core.*numpy._core.* (private)Use public numpy.lib if a path is needed

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Which package is actually compiled against 1.x

The traceback names the extension only sometimes. Import candidates one at a time and read the first failing import:

python
import importlib for mod in ["numpy", "pandas", "scipy", "sklearn", "matplotlib", "cv2", "pyarrow"]: try: importlib.import_module(mod) print("ok ", mod) except Exception as exc: print("FAIL", mod, type(exc).__name__, str(exc)[:80])

pip show <pkg> plus the wheel tag date is the other half of the answer: a wheel published before mid-2025 with a numpy<2 build dependency is the usual suspect.

2. Rebuilding an in-house C extension

A setup.py extension built in a legacy python setup.py install environment picks up whatever NumPy is installed, which is often 1.x from a lockfile:

python
# pyproject.toml — build against NumPy 2 headers, run on both [build-system] requires = ["setuptools>=68", "wheel", "numpy>=2.0.0rc1", "pybind11>=2.12"] build-backend = "setuptools.build_meta"

Building with NumPy 2 headers produces an extension that also runs on 1.x when it sets the appropriate target version (NPY_TARGET_VERSION=NPY_1_21_API_VERSION), which is the intended migration path.

3. pip resolver, constraints and the illusion of correctness

pip resolves Python-level requirements, not ABI compatibility. pip check reports "No broken requirements found" on an environment that cannot import pandas, because pandas' metadata says numpy>=1.23 and NumPy 2 satisfies it:

bash
pip check # may report nothing at all pip list | grep -Ei "numpy|pandas|scipy|scikit"

Pin a coherent set in constraints for reproducible images: numpy==2.2.6, pandas==2.2.3, scipy==1.14.1, scikit-learn==1.5.2.

4. numpy.core imports inside a library

The private module moved. A library that does from numpy.core import numeric fails on 2.x even when it was rebuilt, and the fix belongs in the library:

python
# Before (private, moved in 2.0) from numpy.core.multiarray import normalize_axis_index # After (public API since 1.25) from numpy.lib.array_utils import normalize_axis_index

Until the library is updated, the pin is the only safe workaround — patching numpy.core back into sys.modules breaks on the next minor release.

5. Containers and CI caches that keep an old wheel

pip install --no-cache-dir is not enough when the base image or a private index serves a stale wheel. Check the installed file's build date rather than the version string:

bash
python - <<'PY' import importlib.metadata as m, pathlib d = m.distribution("pandas") f = pathlib.Path(d.locate_file(d.files[0])) print(d.version, f.stat().st_mtime) PY

Rebuild the image with --no-cache and confirm the index actually has a NumPy-2-compatible wheel for your platform and Python version.

6. Mixed requirements from two package managers

conda and pip environments diverge: conda installs a build of NumPy with a different ABI tag than the pip wheel the rest of the stack was compiled against. Pick one channel per environment:

bash
conda list numpy python -c "import numpy; print(numpy.__version__, numpy.get_include())" pip install --upgrade --force-reinstall --no-deps <pkg>

--no-deps is deliberate: it upgrades the extension without dragging in a second NumPy.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Pinning numpy<2 globally as a permanent answer. It works and it blocks every library that adopts NumPy 2 APIs; revisit the pin with a date, not with hope.
  • pip install --upgrade numpy without touching the extensions. The extensions stay compiled for 1.x; upgrade them in the same commit.
  • Assuming the error is in NumPy. NumPy 2 imports fine in the failing environment; the traceback's first frame is a dependent module.
  • np.float_ in application code. It is a removed alias, not an ABI problem, and the fix is a rename — the same message family appears after a clean upgrade.
  • Scalar repr changes breaking tests. NumPy 2 prints np.float64(1.0) instead of 1.0; snapshot tests that compare strings need updating, which is the most common false "regression" after the upgrade.
  • copy=False semantics. In NumPy 2, np.array(obj, copy=False) raises when a copy is unavoidable instead of silently copying; use np.asarray for "copy if needed".
  • Numba and torch ahead of NumPy. Each has its own compatibility window; a NumPy 2.2 install can be fine for pandas and too new for the installed numba. Check the release notes of the dependent package, not NumPy's.

Related tools. When a dependency bump changes an API surface, paste the old and new pyproject.toml or lockfile into the text diff tool to isolate which pin moved, and use the JSON formatter on a serialized array or a model config that a failing test dumps — it usually shows the dtype change that stringifies differently.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.