ComfyUI 缺少 onnx / onnxruntime

症状

ComfyUI 启动时，终端日志中出现以下警告或错误：

WanVideoWrapper WARNING: FantasyPortrait nodes not available: No module named 'onnx'

No module named 'onnxruntime'

DWPose: Onnxruntime not found or doesn't come with acceleration providers, switch to OpenCV with CPU device

原因

onnx 是一个开放的机器学习模型交换格式库，用于加载 .onnx 格式的模型文件。onnxruntime 是微软提供的推理引擎，负责实际执行这些模型。两者经常需要同时安装。

以下 ComfyUI 插件依赖 onnx 或 onnxruntime：

• ComfyUI-WanVideoWrapper — FantasyPortrait 人像风格化功能
• comfyui_controlnet_aux — DWPose 姿态检测（需要 onnxruntime）
• ComfyUI-ReActor — 换脸功能（需要 onnxruntime + insightface）
• ComfyUI_IPAdapter_plus — FaceID 功能（通过 insightface 间接依赖）
• ComfyUI_InstantID — 人脸一致性生成（通过 insightface 间接依赖）
• ComfyUI-PuLID — 人脸保持功能（通过 insightface 间接依赖）

缺少这些库时，依赖它们的节点将不可用，但 ComfyUI 本身和其他插件仍可正常工作。

严重程度

中 — 仅在使用上述插件功能时需要安装。如果你不使用这些功能，此警告可以忽略。

解决方法

方法一：仅安装 CPU 版本（推荐大多数用户）

1. 在 Wonderful Launcher 中打开「环境」页面
2. 找到终端（Terminal）区域
3. 输入以下命令并回车：

   pip install onnx onnxruntime
   

4. 等待安装完成后，重启 ComfyUI

这对大多数场景已经足够。DWPose 等功能在 CPU 模式下也能正常运行，只是速度稍慢。

方法二：安装 GPU 加速版本（NVIDIA 显卡用户）

如果你有 NVIDIA 显卡，可以安装 GPU 版本以加速推理：

pip install onnx onnxruntime-gpu

注意：不要同时安装 onnxruntime 和 onnxruntime-gpu。 onnxruntime-gpu 已经包含 CPU 推理能力。如果之前安装过 onnxruntime，先卸载再安装 GPU 版本：

pip uninstall onnxruntime -y
pip install onnxruntime-gpu

常见安装问题

onnxruntime-gpu 安装后 GPU 不工作

错误信息：

[W:onnxruntime:Default, onnxruntime_pybind_state.cc] LoadLibrary failed with error 126 when trying to load onnxruntime_providers_cuda.dll

原因： onnxruntime-gpu 的 CUDA/cuDNN 版本与当前环境中 PyTorch 使用的版本不匹配。

从 onnxruntime-gpu 1.19 开始，默认要求 CUDA 12.x + cuDNN 9.x。如果你的 PyTorch 使用的是较旧的 cuDNN 8.x（PyTorch 2.3 及以下），就会出现此冲突。

解决方法： 对于大多数 ComfyUI 用户，onnxruntime（CPU 版本）已经够用。如果确实需要 GPU 加速，确保 PyTorch 版本和 onnxruntime-gpu 版本使用相同的 CUDA 大版本号：

PyTorch 版本	cuDNN 版本	适配的 onnxruntime-gpu
2.4 及以上	cuDNN 9.x	1.19+ (默认 pip 安装)
2.3 及以下	cuDNN 8.x	1.18.x

安装指定版本示例：

pip install onnxruntime-gpu==1.18.1

同时安装了 onnxruntime 和 onnxruntime-gpu

症状： GPU 推理无法启用，或出现不可预测的行为。

解决方法： 只保留一个。检查当前安装了哪些：

pip list | findstr onnxruntime

如果看到两个都在，卸载后重新安装需要的版本：

pip uninstall onnxruntime onnxruntime-gpu -y
pip install onnxruntime-gpu

protobuf 版本冲突

错误信息：

TypeError: Descriptors cannot be created directly.

解决方法：

pip install protobuf>=3.20

仍然无法解决？

如果安装过程中遇到其他错误，请通过应用内的「联系我们」按钮联系技术支持，并附上终端中的完整错误信息。