ComfyUI 报错解决记录：NumPy/SciPy 不兼容与 OpenCV 扩展模块缺失

ComfyUI 报错解决记录：NumPy/SciPy 不兼容与 OpenCV 扩展模块缺失

---

玩转 ComfyUI 高阶运维修复专栏 | 免费专栏
【ComfyUI/SD环境管理指南（一）】：如何避免插件安装导致的环境崩溃与快速修复
【ComfyUI/SD环境管理指南（二）】：如何避免插件安装导致的环境崩溃与"外科手术式"修复

---

环境信息

项目	版本
OS	Windows 11
Python	3.12.11
PyTorch	2.7.1+cu126
GPU	NVIDIA RTX 3090 (24GB)
ComfyUI	0.16.3

---

问题一：NumPy/SciPy 不兼容导致启动失败

报错信息

ImportError: numpy._core.multiarray failed to import
ImportError: DLL load failed while importing _multiarray_umath: 找不到指定的模块。

根本原因

• 安装了 NumPy 2.x，但 ComfyUI 及某些依赖库尚未完全兼容

• SciPy 版本与 NumPy 版本不匹配

解决步骤

1. 彻底删除旧版本（手动删除更干净）

# 删除 NumPy 和 SciPy 的所有残留文件
Remove-Item -Recurse -Force H:\PythonProjects3\Win_ComfyUI\.venv\Lib\site-packages\numpy*
Remove-Item -Recurse -Force H:\PythonProjects3\Win_ComfyUI\.venv\Lib\site-packages\scipy*

2. 安装兼容版本（使用 --no-deps 避免依赖冲突）

# 先安装 NumPy 1.x（不安装依赖，避免触发其他包的冲突）
pip install "numpy<2" --no-deps

# 再安装 SciPy（同样使用 --no-deps）
pip install scipy --no-deps

⚠️ 关键提示 ：--no-deps 参数非常重要！

• 防止 pip 自动升级/降级其他包

• 避免触发复杂的依赖解析冲突

• 保持 PyTorch 等核心包不受影响

3. 验证安装

python -c "import numpy; print(f'NumPy: {numpy.__version__}')"
python -c "import scipy; print(f'SciPy: {scipy.__version__}')"
python -c "import torch; print(f'PyTorch: {torch.__version__}')"

预期输出：

NumPy: 1.26.4
SciPy: 1.17.1
PyTorch: 2.7.1+cu126

---

问题二：LayerStyle 节点缺失 OpenCV 扩展模块

报错信息

# 😺dzNodes: LayerStyle -> Cannot import name 'guidedFilter' from 'cv2.ximgproc'
A few nodes cannot works properly, while most nodes are not affected. Please REINSTALL package 'opencv-contrib-python'.                                      
For detail refer to https://github.com/chflame163/ComfyUI_LayerStyle/issues/5                                                                                
# 😺dzNodes: LayerStyle -> Cannot import name 'guidedFilter' from 'cv2.ximgproc'
A few nodes cannot works properly, while most nodes are not affected. Please REINSTALL package 'opencv-contrib-python'.                                      
For detail refer to https://github.com/chflame163/ComfyUI_LayerStyle/issues/5       

根本原因

• cv2.ximgproc 是 OpenCV 的扩展模块 ，仅在 opencv-contrib-python 中提供

• 当前环境可能安装了 opencv-python（基础版）而非 opencv-contrib-python（完整版）

• 或者 opencv-contrib-python 安装损坏/不完整

解决步骤

1. 彻底清理 OpenCV 相关包

# 卸载所有 OpenCV 变体
pip uninstall opencv-python opencv-python-headless opencv-contrib-python -y

2. 重新安装 opencv-contrib-python（使用 --no-deps）

# 使用 --no-deps 避免触发其他依赖冲突
pip install opencv-contrib-python --no-deps

3. 验证修复

python -c "from cv2.ximgproc import guidedFilter; print('✅ guidedFilter 导入成功')"

---

完整修复命令汇总

# ===== 步骤1：修复 NumPy/SciPy =====
# 手动删除残留
Remove-Item -Recurse -Force H:\PythonProjects3\Win_ComfyUI\.venv\Lib\site-packages\numpy*
Remove-Item -Recurse -Force H:\PythonProjects3\Win_ComfyUI\.venv\Lib\site-packages\scipy*

# 重新安装（带 --no-deps）
pip install "numpy<2" --no-deps
pip install scipy --no-deps

# ===== 步骤2：修复 OpenCV =====
# 清理旧版本
pip uninstall opencv-python opencv-python-headless opencv-contrib-python -y

# 安装完整版（带 --no-deps）
pip install opencv-contrib-python --no-deps

# ===== 步骤3：验证并启动 =====
python -c "import numpy, scipy, cv2; from cv2.ximgproc import guidedFilter; print('✅ 所有依赖正常')"
python main.py

如果又出现 numpy 相关报错，请再次重装 numpy ：

pip install "numpy<2" --no-deps
pip install scipy --no-deps

---

关键经验总结

问题	核心解决思路
NumPy 2.x 不兼容	降级到 1.26.4，使用 --no-deps 避免连锁反应
SciPy 版本冲突	配合 NumPy 1.x 版本，同样使用 --no-deps
OpenCV 扩展缺失	安装 opencv-contrib-python 而非 opencv-python
依赖地狱	--no-deps 是救命稻草，手动控制依赖更可控

为什么 --no-deps 如此重要？

在复杂的 ComfyUI 环境中：

• 有 260+ 个自定义节点

• 各节点依赖错综复杂

• 自动依赖解析可能触发"升级 PyTorch → 破坏 CUDA → 整个环境崩溃"的连锁反应

使用 --no-deps 可以：

1. ✅ 精确控制只更新目标包

2. ✅ 避免意外升级/降级核心依赖（PyTorch、CUDA、xFormers 等）

3. ✅ 大幅减少依赖冲突的可能性

4. ✅ 修复过程更快速、更可预测

---

验证成功

修复后 ComfyUI 正常启动：

** ComfyUI startup time: 2026-03-08 14:14:18.365
** Platform: Windows
** Python version: 3.12.11
** pytorch version: 2.7.1+cu126
** xformers version: 0.0.31.post1
** Device: cuda:0 NVIDIA GeForce RTX 3090

To see the GUI go to: http://127.0.0.1:8188

所有节点加载正常，LayerStyle 节点功能恢复！🎉

---

参考链接：

• LayerStyle Issue #5

• NumPy 2.0 迁移指南