ModuleNotFoundError: No module named 'onnx' 或 'onnxruntime'（ComfyUI）

如果你搜索的是 ModuleNotFoundError: No module named 'onnxruntime'、ModuleNotFoundError: No module named 'onnx'、No module named 'onnxruntime.capi'、ComfyUI no module named onnx WanVideoWrapper 或 WanVideoWrapper WARNING: FantasyPortrait nodes not available: No module named 'onnx'，请先确认失败的工作流是否确实使用了依赖 ONNX 的面部、姿态或辅助节点。

对于 WanVideoWrapper，该警告通常出现在 FantasyPortrait 或视频辅助节点附近。对大多数用户而言，CPU 版 onnxruntime 是更稳妥的首选修复方案。仅当工作流确实需要 GPU ONNX Runtime，且你能匹配对应的 CUDA/cuDNN 版本栈时，才考虑使用 GPU 版本。

如果最新可见错误涉及 DWPose、onnxruntime 或 ONNX provider 失败，请以该最新错误为准。不要因为早期日志行提到了不同插件，就切换到另一个包系列。

onnx、onnxruntime 和 onnxruntime.capi 经常出现在同一类人脸、姿态、超分辨率或辅助节点故障中。请把它们纳入同一修复路径，但不要当成同一个包：onnx 用于描述模型文件，onnxruntime 负责运行这些模型。

症状

ComfyUI 启动时，终端日志会显示如下警告或错误：

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

No module named 'onnxruntime'

ModuleNotFoundError: No module named 'onnxruntime.capi'

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

如果你的确切错误是 WanVideoWrapper warning: FantasyPortrait nodes not available: No module named 'onnx'，请留在本页面。这是 ONNX 辅助节点问题，而非通用工作流、模型或 Manager 注册表问题。

原因

onnx 是用于加载 .onnx 模型文件的模型交换库；onnxruntime 是运行这些模型的推理引擎。两者通常需要同时安装，但并非每个工作流都需要两者。

可能依赖 ONNX 或 ONNX Runtime 的常见 ComfyUI 自定义节点包括：

• ComfyUI-WanVideoWrapper - FantasyPortrait 及相关功能
• comfyui_controlnet_aux - DWPose 姿态检测
• ComfyUI-ReActor - 通过 InsightFace / ONNX Runtime 实现的换脸
• ComfyUI_IPAdapter_plus - 通过 InsightFace 实现的 FaceID
• ComfyUI_InstantID - 一致性面部生成
• ComfyUI-PuLID - 面部保留

当这些库缺失时，依赖它们的节点可能不可用，但 ComfyUI 本身及无关的自定义节点仍可正常工作。

选择正确的 ONNX 修复分支

如果你只需要面部、姿态或辅助节点能够加载，CPU 版 onnxruntime 通常是风险更低的修复方案。GPU 版 ONNX Runtime 是优化步骤，而非最稳妥的首选修复。

严重程度

中等 - 仅当你的工作流使用了依赖 ONNX 的姿态、面部或辅助模型时才需要安装这些包。如果该警告来自你不使用的可选节点系列，可以安全忽略。

安装前：使用正确的 Python

在随机终端中直接执行 pip install 是安装后错误依然存在的最常见原因。

如果工具要求输入包名，请输入 onnxruntime 或 onnx，而非完整文本 pip install onnxruntime。如果你从插件依赖文件安装，请在正确的 Python 环境中使用 -r 加上 requirements 文件路径。

解决方案

方案一：安装 CPU 版本

这是大多数用户最稳妥的首选：

python -m pip install onnx onnxruntime

对于官方 Windows 便携包：

.\python_embeded\python.exe -s -m pip install onnx onnxruntime

这对许多使用场景已经足够。DWPose 等功能可以在 CPU 模式下工作，只是速度较慢。

方案二：安装 GPU 加速版本

如果你有 NVIDIA GPU，且工作流能从 ONNX Runtime GPU 加速中受益：

python -m pip install onnx onnxruntime-gpu

不要同时安装 onnxruntime 和 onnxruntime-gpu。如果之前已安装 CPU 版，请先卸载：

python -m pip uninstall onnxruntime -y
python -m 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 使用的运行时栈不匹配。

ONNX Runtime 的 CUDA provider 具有不同的兼容性分组。当前 CUDA 12.x 的 ONNX Runtime 包使用 cuDNN 9.x，与较新的 PyTorch CUDA 12.x 栈兼容，而较旧的 PyTorch 构建版本可能需要旧版 ONNX Runtime GPU。

更稳妥的修复方案： 除非工作流明显受限于 ONNX 推理速度，否则使用 CPU 版 onnxruntime。如果确实需要 GPU 加速，请将 ONNX Runtime GPU 版本与你的 PyTorch CUDA/cuDNN 系列对齐，而不是盲目安装最新包。

onnxruntime 和 onnxruntime-gpu 同时安装

症状： GPU 推理无法激活，或行为变得不稳定。

检查已安装的包：

python -m pip list | findstr onnxruntime

如果两者都存在，只保留你需要的版本：

python -m pip uninstall onnxruntime onnxruntime-gpu -y
python -m pip install onnxruntime

或者，如需 GPU 版：

python -m pip uninstall onnxruntime onnxruntime-gpu -y
python -m pip install onnxruntime-gpu

protobuf 版本冲突

错误信息：

TypeError: Descriptors cannot be created directly.

解决方案： 用引号包裹版本要求，避免 shell 将 > 解释为重定向：

python -m pip install "protobuf>=3.20"

验证安装

python -c "import onnxruntime as ort; print(ort.__version__, ort.get_available_providers())"

如果 GPU 加速正常工作，CUDAExecutionProvider 应出现在 provider 列表中。如果只显示 CPUExecutionProvider，说明安装的是 CPU 版包，或者 GPU provider 未能加载。

仍未解决？

如果安装过程中遇到其他错误，请收集完整的终端信息，以及：

• python --version 的输出
• python -c "import torch; print(torch.__version__, torch.version.cuda)" 的输出
• python -c "import onnxruntime as ort; print(ort.__version__, ort.get_available_providers())" 的输出

将这些信息连同工作流一起保存，再根据 ONNX Runtime provider 输出和你的 Python/Torch/CUDA 版本继续排查。

参考资料

• ComfyUI 故障排除概览
• ComfyUI 自定义节点故障排除指南
• ComfyUI 模型故障排除指南
• ONNX Runtime 安装文档