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.

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:
# 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 foundA minimal reproducer without third-party packages, using an older wheel from the cache:
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 importThe stopgap, which pins the environment back to the ABI the extensions were built for:
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:
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:
| Message | Where it comes from | Fix |
|---|---|---|
A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x | NumPy 2 import hook | Upgrade or rebuild the extension |
AttributeError: _ARRAY_API not found | Extension body | Same |
ImportError: numpy.core.multiarray failed to import | Dependent library | Same |
ModuleNotFoundError: No module named 'numpy.core' | Library importing a private path | Library upgrade (numpy._core is private) |
RuntimeError: Numpy is not available | torch/torchvision version mismatch | Upgrade the torch pair |
AttributeError: np.float_ was removed | Application code using removed aliases | Use np.float64 |
The removals that break day-two code after the upgrade:
| Removed in NumPy 2 | Replacement | Note |
|---|---|---|
np.float_ | np.float64 | Alias removed, same type |
np.complex_ | np.complex128 | |
np.unicode_ | np.str_ | |
np.string_ | np.bytes_ | |
np.NaN, np.Inf, np.infty | np.nan, np.inf | Constants removed |
np.mat | np.asmatrix | Matrix subclass discouraged |
np.alltrue, np.sometrue | np.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:
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:
# 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:
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:
# 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_indexUntil 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:
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)
PYRebuild 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:
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<2globally 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 numpywithout 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 of1.0; snapshot tests that compare strings need updating, which is the most common false "regression" after the upgrade. copy=Falsesemantics. In NumPy 2,np.array(obj, copy=False)raises when a copy is unavoidable instead of silently copying; usenp.asarrayfor "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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.