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은 워크플로에서 실제로 GPU 가속 추론이 필수적이고, 사용 중인 CUDA/cuDNN 버전 환경 스택을 완벽하게 일치시킬 수 있는 경우에만 검토하십시오.

DWPose, onnxruntime 또는 ONNX 실행 프로바이더 오류가 발생한 경우 해당 오류 로그를 기준으로 삼으세요.

2026년 7월 8일 기준 Wonderful Launcher 원격 분석 데이터에 따르면, onnxruntime은 지난 30일 동안 203회의 치명적인 이벤트와 6회의 설치 과정에서 감지되었고, onnx는 111회의 치명적 이벤트와 4회의 설치 중에 보고되었습니다. 또한 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 관련 보조 노드의 문제이며, ComfyUI 코어나 Manager의 전체적인 오류는 아닙니다.

에러 원인

onnx는 .onnx 포맷의 모델 파일을 로드하고 메타데이터를 조작하기 위한 라이브러리이고, onnxruntime은 이러한 모델 파일을 구동하는 최적화 추론 엔진입니다. 대개 둘 다 설치해야 하지만 모든 워크플로에서 요구하는 것은 아닙니다.

ONNX 또는 ONNX Runtime에 의존하는 주요 ComfyUI 커스텀 노드는 다음과 같습니다.

• ComfyUI-WanVideoWrapper - FantasyPortrait 등 동영상 보조 가속
• comfyui_controlnet_aux - DWPose 자세 검출
• ComfyUI-ReActor - 얼굴 교체 (InsightFace / ONNX Runtime 기반)
• ComfyUI_IPAdapter_plus - FaceID (InsightFace 기반)
• ComfyUI_InstantID - 일관성 있는 얼굴 생성
• ComfyUI-PuLID - 얼굴 특징 유지

이 라이브러리들이 유실된 상태라면 해당 노드들은 로드되지 않지만, ComfyUI 자체와 그 외 무관한 노드들은 평소대로 작동합니다.

올바른 ONNX 복원 옵션 선택

단순히 커스텀 노드 로드 실패 에러만 제거하고 싶다면 CPU 버전 onnxruntime을 설치하는 것이 리스크가 가장 적습니다. GPU 버전 ONNX Runtime은 최적화 단계이므로 복구 첫 단계로는 적합하지 않습니다.

설치 및 해결 단계

정확한 Python 환경 확인

설치 명령은 ComfyUI를 직접 실행하는 Python 환경 경로에서 수행해야 합니다.

해결 방안 1: CPU 버전 설치 (권장)

대부분의 일반 환경에서 가장 안전하고 확실한 설치 방식입니다.

python -m pip install onnx onnxruntime

Windows 포터블 버전인 경우:

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

DWPose 등의 노드는 CPU 모드에서도 안정적으로 구동됩니다. (속도가 다소 느려질 뿐입니다.)

해결 방안 2: GPU 가속 버전 설치

NVIDIA GPU 환경을 갖추고 있으며 ONNX 추론 가속이 꼭 필요한 경우:

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 가속이 작동 안 함

에러: LoadLibrary failed with error 126 when trying to load onnxruntime_providers_cuda.dll 원인: onnxruntime-gpu가 호출하는 CUDA/cuDNN 버전 스택과 현재 PyTorch 환경 버전에 괴리가 있습니다. 해결: 추론 속도에 큰 지장이 없는 한 CPU 버전 onnxruntime으로 되돌리는 것이 좋습니다. GPU 가속을 유지하려는 경우, 현재 설치된 PyTorch의 CUDA/cuDNN 환경 버전에 정밀 매칭되는 특정 ONNX Runtime 휠 패키지를 찾아 맞춤 설치해야 합니다.

CPU 버전과 GPU 버전의 혼재

증상: GPU 가속이 비활성화되거나 런타임 구동이 불안정해집니다. 아래를 실행해 패키지 설치 목록을 확인하세요.

python -m pip list | findstr onnxruntime

목록에 두 패키지가 동시에 나타난다면, 둘 다 언설치한 뒤 원하는 한 종류만 깔끔하게 설치합니다.

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

protobuf 버전 충돌

에러: TypeError: Descriptors cannot be created directly. 해결: protobuf 버전을 지정해 복구해 줍니다. (쉘 해석 오류 방지를 위해 다운로드 규격을 큰따옴표로 감싸 줍니다.)

python -m pip install "protobuf>=3.20"

설치 검증

동일한 Python 환경 경로상에서 아래를 실행해 검사합니다.

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

GPU 가속 런타임이 성공적으로 구성되었다면 출력 리스트 목록에 'CUDAExecutionProvider'가 포함되어 표시됩니다. 'CPUExecutionProvider'만 뜬다면 CPU 전용 패키지가 얹어졌거나 GPU 프로바이더 초기화에 실패한 것입니다.

관련 가이드

• ComfyUI No Module Named 'triton'
• ComfyUI No module named 오류 복구
• ComfyUI 의존성 충돌

출처 참조

• ONNX Runtime 공식 설치 가이드라인