python -c "import numpy; print(numpy.__version__)"If that prints a version number, NumPy is there. If it throws an ImportError, you need to install it in the correct environment.
Shape and Dimension Mismatch Errors
This error type shows up when custom nodes try to perform operations on arrays or tensors with incompatible shapes. It is less about NumPy itself and more about how the node is structured but you still need NumPy loaded correctly to even see what went wrong.
The typical scenario involves a node expecting a specific tensor shape (say, (H, W, 3) for an RGB image) and receiving something different because of how the input data was preprocessed. The error message usually points to the exact line in the custom node code where the mismatch occurred.
- Check that your input images or tensors match what the node expects
- Verify the node has not been updated to a version incompatible with your current setup
- Look at any preprocessing steps between nodes something might be reshaping data unexpectedly
CustomScriptNumpy and similar nodes that wrap raw NumPy operations are particularly unforgiving about shape mismatches, so double-check your input dimensions before diving into debugging.
General Import and Attribute Errors
Beyond the big three categories above, there are scattered import errors that can show up for various reasons. Some involve missing dependencies that NumPy itself depends on (like BLAS libraries), while others come from conflicting package versions in your environment.
A common one is ModuleNotFoundError for specific NumPy submodules like numpy.fft or numpy.linalg. These are almost always resolved by ensuring you have a compatible NumPy version installed in the right environment.
Dependency conflicts happen more often than people expect. A custom node might declare numpy>=1.20 as a requirement, and pip will happily install the latest available version which could be 2.x if that is what your system has.
# requirements-comfyui.txt\nnumpy==1.26.4\n# Add any other pinned dependencies here- Pin your NumPy version in ComfyUI Manager. After installing 1.26.4, mark it as pinned or added to a requirements file so future updates do not pull in the incompatible 2.x series automatically.
- Keep ComfyUI and custom nodes updated together. Many node authors release patches for NumPy 2.x compatibility check their repositories regularly.
- Avoid system-wide Python modifications while running ComfyUI. If your system Python upgrades to a newer NumPy, it can interfere with the portable version bundled environment.
Community Resources and Further Reading
The ComfyUI community has been active in documenting Numpy Errors in ComfyUI. Some useful places to check:
- GitHub Issues. The main ComfyUI repository tracks NumPy compatibility problems under issue #5664 and related threads.
- Reddit discussions in r/comfyui frequently post troubleshooting steps on r/comfyui when they encounter these errors.
- Node documentation pages. Some custom nodes like CustomScriptNumpy include their own compatibility notes and required versions.
Quick Reference Summary
Here is a condensed version of everything above for when you need to look something up quickly:
| Error Type | Cause | Solution |
|---|---|---|
| AttributeError or ImportError | NumPy 2.0+ breaking changes with custom nodes | Downgrade to numpy==1.26.4 via ComfyUI Manager or terminal. |
| “NumPy is not available” | Embedded Python fails to link NumPy library or it was corrupted or deleted | Reinstall via ComfyUI Manager Install PIP Packages numpy==1.26.4 |
| Shape or Dimension Mismatch | Operations on incompatible tensor or array dimensions in custom nodes | Verify input tensor shapes and ensure the NumPy script syntax is correct. |
# If running ComfyUI with a virtual environment, activate it first:\nsource venv/bin/activate\n\n# Then install the specific version:\npip install numpy==1.26.4If you are using ComfyUI Manager built-in package installer, navigate to Install PIP Packages, type numpy==1.26.4, and hit install. The manager handles the virtual environment correctly in most cases.
The NumPy is not available Error
This one sounds dramatic but usually has a boring explanation. It occurs when the embedded Python environment in portable versions fails to link to the NumPy library, or when the package was accidentally deleted or corrupted.
If you are running ComfyUI from a portable zip and seeing this error, your first instinct might be to check whether NumPy is actually installed on your system. But that is not quite right because the portable version comes with its own bundled Python environment. The problem is not that NumPy is not on your system; it is that the ComfyUI bundle cannot find it.
- Accidental deletion or corruption. If you ran a system package manager update that touched Python libraries, you might have overwritten files in the portable bundle Lib site-packages numpy directory.
- Incomplete extraction. Portable zip files sometimes extract incompletely on Windows due to path length limitations. The NumPy folder might be truncated or missing entirely.
- Antivirus interference. Some antivirus software flags Python libraries as suspicious and quarantines them silently, especially if they contain compiled extensions (.pyd files).
The fix is to reinstall through the manager. Navigate to ComfyUI Manager Install PIP Packages, type numpy==1.26.4, and hit install.
python -c "import numpy; print(numpy.__version__)"If that prints a version number, NumPy is there. If it throws an ImportError, you need to install it in the correct environment.
Shape and Dimension Mismatch Errors
This error type shows up when custom nodes try to perform operations on arrays or tensors with incompatible shapes. It is less about NumPy itself and more about how the node is structured but you still need NumPy loaded correctly to even see what went wrong.
The typical scenario involves a node expecting a specific tensor shape (say, (H, W, 3) for an RGB image) and receiving something different because of how the input data was preprocessed. The error message usually points to the exact line in the custom node code where the mismatch occurred.
- Check that your input images or tensors match what the node expects
- Verify the node has not been updated to a version incompatible with your current setup
- Look at any preprocessing steps between nodes something might be reshaping data unexpectedly
CustomScriptNumpy and similar nodes that wrap raw NumPy operations are particularly unforgiving about shape mismatches, so double-check your input dimensions before diving into debugging.
General Import and Attribute Errors
Beyond the big three categories above, there are scattered import errors that can show up for various reasons. Some involve missing dependencies that NumPy itself depends on (like BLAS libraries), while others come from conflicting package versions in your environment.
A common one is ModuleNotFoundError for specific NumPy submodules like numpy.fft or numpy.linalg. These are almost always resolved by ensuring you have a compatible NumPy version installed in the right environment.
Dependency conflicts happen more often than people expect. A custom node might declare numpy>=1.20 as a requirement, and pip will happily install the latest available version which could be 2.x if that is what your system has.
# requirements-comfyui.txt\nnumpy==1.26.4\n# Add any other pinned dependencies hereThen run pip install -r requirements-comfyui.txt before starting ComfyUI. This ensures consistency across reboots and prevents accidental upgrades from pulling in incompatible versions.
How to Prevent These Issues Going Forward
Once you have worked through a NumPy error, it is worth setting up some prevention measures so they do not keep coming back. The goal is to make your ComfyUI environment stable and predictable.
- Pin your NumPy version in ComfyUI Manager. After installing 1.26.4, mark it as pinned or added to a requirements file so future updates do not pull in the incompatible 2.x series automatically.
- Keep ComfyUI and custom nodes updated together. Many node authors release patches for NumPy 2.x compatibility check their repositories regularly.
- Avoid system-wide Python modifications while running ComfyUI. If your system Python upgrades to a newer NumPy, it can interfere with the portable version bundled environment.
Community Resources and Further Reading
The ComfyUI community has been active in documenting these issues. Some useful places to check:
- GitHub Issues. The main ComfyUI repository tracks NumPy compatibility problems under issue #5664 and related threads.
- Reddit discussions. Users frequently post troubleshooting steps on r/comfyui when they encounter these errors.
- Node documentation pages. Some custom nodes like CustomScriptNumpy include their own compatibility notes and required versions.
Quick Reference Summary
Here is a condensed version of everything above for when you need to look something up quickly:
| Error Type | Cause | Solution |
|---|---|---|
| AttributeError or ImportError | NumPy 2.0+ breaking changes with custom nodes | Downgrade to numpy==1.26.4 via ComfyUI Manager or terminal. |
| “NumPy is not available” | Embedded Python fails to link NumPy library or it was corrupted or deleted | Reinstall via ComfyUI Manager Install PIP Packages numpy==1.26.4 |
| Shape or Dimension Mismatch | Operations on incompatible tensor or array dimensions in custom nodes | Verify input tensor shapes and ensure the NumPy script syntax is correct. |
The takeaway is that most of these problems have simple solutions. Pin your version, keep things updated, and do not panic when ComfyUI throws a NumPy error because it is usually just telling you to install the right version for your setup.
Also check out this article about fixing a specific numpy error in comfyui by doing a downgrade