ComfyUI에서 No module named 'insightface'가 뜰 때의 Windows 복구

No module named 'insightface' 는 system Python 이 아니라 ComfyUI 를 실제로 시작한 Python 환경 을 고쳐야 해결됩니다.

Windows 에서 pip install insightface 를 바로 치면 소스 빌드로 넘어가면서 C++ 컴파일 오류가 나는 경우가 많습니다. 가능하면 Python 버전에 맞는 wheel 을 먼저 쓰고, 얼굴 workflow 가 실제로 필요할 때만 ONNX Runtime 까지 추가하세요.

언제 필요한가

• ReActor face swap
• IPAdapter FaceID
• InstantID
• PuLID

얼굴 관련 노드가 필요 없는 workflow 라면 굳이 지금 설치할 필요는 없습니다.

먼저 확인

• 에러를 낸 노드가 정말 face workflow 인가
• 패키지를 넣는 위치가 ComfyUI 의 Python 인가
• onnxruntime 까지 필요한 노드인가

portable 기준:

.\python_embeded\python.exe -s -m pip show insightface

Windows 에서 자주 막히는 이유

• PyPI insightface 는 소스 배포라 빌드 도구를 요구함
• 잘못된 Python 에 설치함
• NumPy / ONNX Runtime 스택이 이미 꼬여 있음

복구 순서

1단계: ComfyUI가 쓰는 Python 확인

패키지는 ComfyUI를 실제로 시작하는 Python에 설치해야 합니다. 포터블 패키지라면 루트 폴더에서 다음 명령으로 버전을 확인하세요.

.\python_embeded\python.exe -s --version

수동 Git + venv 설치는 가상환경을 활성화한 뒤 python --version을 사용합니다. Desktop 또는 관리형 런처는 앱의 환경/터미널 도구를 사용하며, 포터블 폴더 구조를 가정하면 안 됩니다.

2단계: Python 버전에 맞는 미리 빌드된 Windows wheel 설치

Windows에서는 일반 pip install insightface가 네이티브 코드를 소스에서 빌드하려 하기 때문에 권장하지 않습니다. ReActor 생태계에서 제공하는 커뮤니티 wheel 중 Python 버전과 맞는 파일을 선택하세요.

포터블 패키지에서는 위 명령의 python -m pip 부분을 다음으로 바꿉니다.

.\python_embeded\python.exe -s -m pip

이 파일들은 공식 InsightFace PyPI 프로젝트가 배포한 wheel이 아니라, 로컬 C++ 컴파일을 피하기 위해 쓰는 커뮤니티 wheel입니다. 신뢰할 수 있는 출처일 때만 다운로드하고, 정확한 URL과 버전을 기록하며, 가능하면 백업된 환경에서 진행하세요. 위험을 판단할 수 없다면 설치하지 말고, 지원되는 환경이나 노드 작성자가 문서화한 의존성 경로를 사용하세요.

3단계: 워크플로가 요구할 때만 ONNX Runtime 추가

InsightFace는 ONNX Runtime을 추론 백엔드로 사용합니다. CPU 버전만으로 충분한 경우가 많습니다.

python -m pip install onnxruntime

NVIDIA GPU 가속이 필요한 경우에만 다음을 사용합니다.

python -m pip install onnxruntime-gpu

onnxruntime_providers_cuda.dll 오류가 나면 PyTorch의 CUDA/cuDNN 계열과 맞지 않는 경우가 많습니다. 다른 패키지를 더 바꾸기 전에 ComfyUI ONNX / ONNXRuntime Missing을 확인하세요.

4단계: NumPy 다운그레이드는 최후의 수단

InsightFace가 언급되었다는 이유만으로 NumPy를 내리지 마세요. 현재 ComfyUI 환경은 NumPy 2.x를 정상적으로 사용할 수 있습니다.

꼭 필요한 얼굴 플러그인에서 실제 NumPy 호환성 오류가 확인될 때만, 먼저 백업하거나 별도 환경에서 다음을 시도합니다.

python -m pip install "numpy<2"

그 뒤 ComfyUI를 재시작하고, 변경이 필요했던 얼굴 워크플로만 테스트하세요.

5단계: ComfyUI 완전 재시작

InsightFace 또는 ONNX Runtime을 설치한 뒤에는 ComfyUI를 완전히 재시작해야 합니다. 이미 가져오기에 실패한 플러그인은 다음 백엔드 시작 전까지 노드를 등록하지 않습니다.

설치 확인

같은 환경에서 다음을 실행합니다.

python -c "import insightface; print(insightface.__version__)"

커뮤니티 wheel 경로를 사용했다면 보통 0.7.3이 출력됩니다.

계속 실패한다면

다음 정보를 함께 보관하세요.

• 전체 IMPORT FAILED traceback
• python --version 출력
• python -c "import torch; print(torch.__version__, torch.version.cuda)" 출력
• CPU 또는 GPU ONNX Runtime 중 무엇을 설치했는지

관련 문서

• ComfyUI ONNX / ONNXRuntime Missing
• ComfyUI Plugin Import Failed
• ComfyUI No Module Named