ComfyUI “NumPy 1.x Compiled” Import Error: Fix the NumPy 2 ABI Clash Without Reinstalling Everything

You update a custom node, or run ComfyUI’s dependency updater, restart the server — and suddenly half your nodes refuse to load. The console prints a familiar, frustrating block:

A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x as it may crash. To support both 1.x and 2.x versions of NumPy, modules must be compiled with NumPy 2.0. Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.

This is not a custom node being “broken,” and it is not fixed by reinstalling ComfyUI. It is a binary ABI incompatibility between NumPy 2.x and a compiled extension (usually PyTorch, OpenCV, insightface, or numba) that was built against NumPy 1.x. This guide walks through exactly what is happening, how to confirm the root cause in under a minute, and the two correct fixes — plus how to stop the clash from returning on the next update.

This article is a documentation-based analysis drawn from the official NumPy troubleshooting guide and confirmed ComfyUI issue reports. No benchmark or “tested on my machine” performance numbers are claimed here; the commands are the same ones maintainers recommend in the linked sources.

What the error actually means

NumPy 2.0 (released June 2024) changed its C extension API. A package that contains compiled C or Cython code — PyTorch, OpenCV, insightface (used by face-swap nodes like ReActor), numba, and many others — is compiled against a specific NumPy ABI version. If that package was built against NumPy 1.x and you later install NumPy 2.x, the compiled module refuses to import, and you get the message above.

The key sentence in the error is the last one before you start Googling: “the easiest solution will be to downgrade to ‘numpy<2’ or try to upgrade the affected module.” That is the entire decision space. You either move NumPy back to 1.x, or move the offended package forward to a NumPy-2–compatible build.

Notice the chain of symptoms it triggers. Because PyTorch itself often fails to initialize NumPy cleanly, the failure can cascade into misleading downstream errors:

• RuntimeError: Numpy is not available on a SaveImage node
• UserWarning: Failed to initialize NumPy: _ARRAY_API not found
• AttributeError: _ARRAY_API not found
• ValueError: numpy.dtype size changed, may indicate binary incompatibility
• Multiple (IMPORT FAILED) summary lines for nodes that were fine yesterday

The common thread is that the first genuine traceback — the one above the IMPORT FAILED summary — points at NumPy, not at the node. According to NumPy’s own troubleshooting guide for ImportError, when you hit this, “search the traceback (from the back) to find the first line that isn’t inside NumPy to see which package has the incompatibility.” That single step is the fastest route from wall-of-text to diagnosis.

Diagnose before you downgrade: use pip check

Do not blindly run pip install "numpy<2" the moment you see the error. There are two distinct failure classes, and they want opposite fixes. It is worth thirty seconds to find out which one you have.

The cleanest confirmation is pip check, which reports incompatible version pins across the whole environment. Run it against the Python interpreter that actually launches ComfyUI:

# Windows portable build (ComfyUI ships its own embedded interpreter)
.\python_embeded\python.exe -m pip check

# Linux / macOS, or any venv-based install — activate the SAME venv ComfyUI uses first
python -m pip check

Representative output when NumPy 2.x is the culprit looks like this:

numba 0.59.1 requires numpy<2.1,>=1.22, but you have numpy 2.3.2.

That one line tells you a compiled package (numba) is pinned to NumPy 1.x while NumPy 2.3.2 is installed. The two options follow directly:

1. Downgrade NumPy below 2 to match the package’s existing pin (fastest, but holds the whole environment at 1.x).
2. Upgrade the offending package to a release built against NumPy 2.x (cleaner long term, but not always available — some packages took months to ship NumPy-2 wheels).

This decision is documented by NumPy maintainers: “The best solution will usually be to upgrade the failing package… however, upgrading may not always be possible because a compatible version does not yet exist.” When the compatible build does not exist, downgrading NumPy is the correct, supported fallback.

Fix 1: pin NumPy back below 2 (the safe range)

The most common fix — and the one most users reach for — is to pin NumPy to a recent 1.x line. There is one important gotcha hidden in this otherwise trivial command: do not pin an ancient release like numpy==1.23.5.

Modern ComfyUI builds ship Python 3.12+, and older NumPy 1.x releases fail to build on those interpreters because current setuptools removed the ImpImporter attribute those old NumPy wheels expected. The NumPy 1.x range that actually supports Python 3.12 is roughly >=1.26. The maintainer-recommended safe range is:

# Windows portable
.\python_embeded\python.exe -m pip install "numpy>=1.26,<2"

# Linux / macOS venv
python -m pip install "numpy>=1.26,<2"

A specific release that appears repeatedly in confirmed ComfyUI issue threads (GitHub issue #5664) is numpy==1.26.4, the last 1.x release. If you prefer a hard pin:

.\python_embeded\python.exe -m pip install numpy==1.26.4

Restart ComfyUI completely afterward — closing the browser tab is not enough. The custom-node imports happen once at server startup, so you must terminate and relaunch the Python process for the change to take effect.

Fix 2: upgrade the NumPy-1.x–compiled package instead

Holding NumPy at 1.x forever is not a strategy; it is a stopgap. The cleaner fix, when your other packages allow it, is to move the offending package to a NumPy-2–compatible build. Most often that package is PyTorch.

If pip check or the traceback points at PyTorch (look for torch/_subclasses/functional_tensor.py or torch/csrc/utils/tensor_numpy.cpp in the warnings), the fix is to upgrade PyTorch to a release compiled against NumPy 2.x. For CUDA builds, install from the CUDA wheel index rather than the default PyPI index:

# Use --index-url, not --extra-index-url, so pip resolves from the CUDA wheel index
.\python_embeded\python.exe -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

Read the whole traceback before choosing this path. If the incompatibility is coming from opencv-python, insightface, or numba rather than PyTorch, upgrade that specific package (pip install --upgrade opencv-python and so on). The goal in both directions is the same, and it is the sentence NumPy’s guide states plainly: “the goal is one consistent NumPy ABI across the environment.”

Why it keeps coming back — and how to stop it

This error rarely appears out of nowhere. It almost always arrives right after one of two events, and understanding which one is what prevents the recurrence:

• You ran ComfyUI’s “update all” or a dependency updater. Scripts like update_comfyui_and_python_dependencies.bat on Windows Portable reinstall the full requirements.txt and can pull in a newer NumPy while other packages still pin 1.x. In GitHub issue #9156, a user triggered exactly this by running the updater, which silently bumped NumPy to 2.3.2 and broke most custom nodes.
• You installed a new node pack. A single node’s requirements.txt can pip install a NumPy 2.x (or, less commonly, force a NumPy 1.x downgrade under other nodes), shifting the ABI underneath everything else.

Two habits prevent most of this. First, preview before you install — pass --dry-run to see what a node’s requirements will actually change:

.\python_embeded\python.exe -m pip install -r custom_nodes\SomeNode\requirements.txt --dry-run

Second, prefer ComfyUI-Manager for node installs and updates rather than raw pip or the manual dependency updater. Manager installs dependencies into the correct embedded interpreter and is more conservative about bumping shared core packages like NumPy and PyTorch. Maintainers and long-time users in the issue threads repeatedly steer people back to Manager for exactly this reason: it is the least likely path to clobber the environment.

If you must update PyTorch or CUDA manually, do it deliberately and check pip check immediately afterward. Treat a clean pip check as the exit condition for any dependency change, the same way you treat a passing test suite as the exit condition for a code change.

Verification: how you know it is actually fixed

Pinning NumPy and restarting is only half the job. Confirm the fix before you queue a real generation:

1. Restart ComfyUI from a visible terminal (or open the desktop log) and confirm the raw import error is gone, not just buried. The node summary lines should read 0.0 seconds without (IMPORT FAILED).
2. Run pip check again and confirm it exits with no incompatible pins.
3. Queue the smallest known-good workflow using one of the previously failing nodes, and confirm it executes.
4. Watch for the secondary symptoms — if RuntimeError: Numpy is not available or Failed to initialize NumPy reappears on a SaveImage node, the ABI clash is not fully resolved and you still have a mixed environment.

For more context on reading ComfyUI import failures generally, see our guide on diagnosing “No module named” errors and broken custom nodes, and for the wider symptom-first workflow, the official ComfyUI troubleshooting guide is the authoritative reference. The definitive write-up on this specific ABI error lives in the NumPy ImportError troubleshooting documentation.

Conclusion

The “compiled using NumPy 1.x” error is intimidating because it says very little and sprays misleading secondary warnings. But it resolves to a binary choice that NumPy’s own documentation spells out: either downgrade NumPy below 2, or upgrade the compiled package to a NumPy-2 build. Diagnose with pip check first, pin to the safe numpy>=1.26,<2 range if you downgrade (never an ancient 1.23.x), and use --dry-run plus ComfyUI-Manager so the next update doesn’t silently recreate the clash. One consistent NumPy ABI is the whole fix.