ComfyUI 提示 No module named 'onnx' 或 'onnxruntime'：怎麼修

如果 ComfyUI 日誌裡出現 No module named 'onnx' 或 No module named 'onnxruntime'，先別急著裝 GPU 版。 對大多數用戶來說，先安裝 CPU 版 onnxruntime 是更穩的第一步。

典型症狀

啟動日誌裡常見這些信息：

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 是運行這些模型的推理引擎。 很多人把兩者混為一談，但並不是每個工作流都需要同時裝它們。

常見依賴 ONNX 或 ONNX Runtime 的 ComfyUI 節點包括：

• ComfyUI-WanVideoWrapper
• comfyui_controlnet_aux（例如 DWPose）
• ComfyUI-ReActor
• ComfyUI_IPAdapter_plus
• ComfyUI_InstantID
• ComfyUI-PuLID

當這些包缺失時，依賴它們的節點會不可用，但 ComfyUI 本體和其他不相關節點可能仍然正常。

嚴重程度

中等。 如果這只是某個你根本沒在用的可選節點發出的警告，可以先忽略。只有你的工作流真的依賴 ONNX 路線時，才需要修。

安裝前先確認：你用的是對的 Python

很多“明明裝了還是報錯”的情況，本質上是把包裝進了 錯誤的 Python 環境。

解決方法

方案 1：先裝 CPU 版

這是大多數用戶最安全的第一步：

python -m pip install onnx onnxruntime

官方 Windows portable 包則執行：

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

這已經能覆蓋很多場景，例如 DWPose 走 CPU 推理，只是速度會慢一些。

方案 2：確實需要時再裝 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 推理上，先退回 CPU 版 onnxruntime
• 只有確實需要 GPU 加速時，再去匹配對應的 CUDA / cuDNN 版本

同時裝了 onnxruntime 和 onnxruntime-gpu

表現： GPU provider 啟不起來，或者行為反覆不穩定。

檢查當前安裝：

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。 如果只有 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())"
• 完整安裝報錯

如果你要更快恢復，先用 Wonderful Launcher 檢查當前環境、任務日誌和依賴狀態；需要人工協助時再走支持渠道。

參考來源

• ComfyUI 官方排障總覽
• ComfyUI 自定義節點排障
• ComfyUI 模型問題排障
• ONNX Runtime 安裝文檔