ModuleNotFoundError: No module named 'cv2' (ComfyUI) 해결 가이드
ComfyUI의 ModuleNotFoundError: No module named 'cv2' 오류 해결 가이드. opencv-python-headless, opencv-contrib-python 등의 패키지 충돌 해결법.
30초 판단 분기
사용하려는 워크플로가 동영상 파일 읽기(VideoHelperSuite), 포즈 검출(ControlNet DWPose), 얼굴 교체(ReActor) 등과 무관하다면, 이 에러 로그는 단순히 무시해도 되는 로그입니다. 그냥 무시하십시오. 만약 이로 인해 커스텀 노드가 로드되지 않아 작업 진행이 중단된다면, ComfyUI 구동 Python 경로에 올바른 OpenCV 패키지 버전을 설치해 주어야 합니다.
ComfyUI 실행 시 **ModuleNotFoundError: No module named 'cv2'**가 발생하면, 메인 Windows OS가 아닌 ComfyUI 구동에 쓰이는 특정 Python 가상환경 내에 올바른 OpenCV 라이브러리를 설치해야 합니다.
Windows 환경에서는 여러 종류의 OpenCV 패키지(예: opencv-python과 opencv-python-headless)가 가상환경에 혼재하여 설치될 때, 공통 네임스페이스인 cv2 모듈이 깨져 임포트 에러가 반복적으로 나는 고유한 함정이 존재합니다.
정밀 에러 로그
터미널창이나 부팅 로그에 아래와 같이 에러가 기록된다면 본 가이드의 복원 대책이 필요합니다.
ModuleNotFoundError: No module named 'cv2'또는 다음과 같은 패키지 미설치 로그도 동일 원인입니다.
albumentations requires opencv-python-headless, which is not installed
mediapipe requires opencv-contrib-python, which is not installed
mmcv requires opencv-python, which is not installed에러 원인
OpenCV는 Python 상에서 cv2 모듈을 제공하며, 수많은 커스텀 노드들이 이를 활용해 이미지 리사이즈, 자르기, 색상 변환, 포즈 추출용 전처리, 동영상 프레임 디코딩 등을 처리합니다.
주된 원인은 다음과 같습니다.
- ComfyUI 구동 Python 환경 내에 OpenCV 라이브러리가 전혀 설치되지 않음.
- 서로 충돌하는 여러 OpenCV 패키지 변형이 가상환경에 동시에 설치되어
cv2경로가 파손됨. - NumPy 라이브러리와의 버전 충돌 또는 Windows C++ 런타임 DLL 부재로 인해 로드가 거부됨.
OpenCV 패키지 종류 및 특징
PyPI의 아래 공식 패키지들은 전부 동일한 cv2 임포트 모듈 명칭을 공유합니다.
| 패키지 이름 | 포함 내용 | 권장 용도 |
|---|---|---|
opencv-python | 핵심 모듈 + GUI 윈도우 지원 | 독립된 창으로 이미지를 띄워 볼 때 (cv2.imshow 등) |
opencv-python-headless | 핵심 모듈, GUI 기능 배제 | 웹서버 및 백엔드 런타임용. ComfyUI 환경에서 가장 추천되는 기본 패키지입니다. |
opencv-contrib-python | 핵심 + 추가 확장 모듈 + GUI | 특수 알고리즘 연산과 별도 창 출력이 필요할 때 |
opencv-contrib-python-headless | 핵심 + 추가 확장 모듈, GUI 배제 | 특수 알고리즘이 필요하나 별도 창 출력은 없을 때 |
※ 중요한 규칙: 한 가상환경 내에는 단 하나의 OpenCV 패키지만 남겨 두어야 합니다. 중복 설치 시 네임스페이스가 엉켜 ModuleNotFoundError를 반드시 유발합니다.
복구 및 해결 단계
1단계: 정확한 Python 환경 확인
설치 명령은 ComfyUI를 직접 실행하는 Python 환경 경로에서 수행해야 합니다.
| 설치 환경 구분 | 실행 명령 형태 |
|---|---|
| 공식 Windows Standalone 포터블 버전 | 포터블 루트 디렉토리에서 실행: .\python_embeded\python.exe -s -m pip ... |
| 수동 설치 환경 (Git + venv) | 가상 환경 venv를 활성화한 상태에서 실행: python -m pip ... |
| ComfyUI Desktop 및 타 실행기 | 앱 전용 통합 개발 콘솔 환경을 활용 |
2단계: 현재 설치된 OpenCV 확인
터미널에 아래를 입력해 현재 환경의 OpenCV 중복 여부를 점검하세요.
python -m pip list | findstr opencv포터블 버전인 경우:
.\python_embeded\python.exe -s -m pip list | findstr opencv목록에 2개 이상의 패키지가 검출되면 즉시 하나를 제외하고 정리해야 합니다.
3단계: 삭제 및 재설치
상황 A: OpenCV 패키지가 아예 없는 경우
python -m pip install opencv-python-headless상황 B: 중복 설치되어 있거나 임포트가 계속 깨지는 경우 모든 기존 OpenCV 잔여물을 삭제한 뒤, 권장 패키지 하나만 깨끗하게 설치합니다.
python -m pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless
python -m pip install opencv-python-headless상황 C: NumPy 버전 대치 문제 일부 노드가 NumPy 1.x를 요구한다고 해서 무작정 전체 환경을 1.x로 내리지 마십시오. 최신 ComfyUI 스택은 NumPy 2.x와 호환됩니다. 특정 패키지에서 에러가 정말로 반복될 때만 가상환경 백업 후 버전을 매칭해 설치하세요.
상황 D: 특정 노드가 contrib (확장 모듈)을 필요로 할 때
기존 opencv-python-headless 위에 덮어쓰지 말고, 언설치 명령어로 정리한 다음 opencv-contrib-python-headless만 깔끔하게 설치해 주어야 에러가 나지 않습니다.
4단계: 검증
설치 후 동일 Python 환경에서 테스트해 버전이 잘 찍히는지 봅니다.
python -c "import cv2; print(cv2.__version__)"정상 동작한다면 ComfyUI 서버를 다시 켜고 결과를 관찰하세요.
관련 가이드
출처 참조
실제 ComfyUI 환경에서 생긴 문제라면 먼저 무료로 Wonderful Launcher 로 현재 머신을 확인하세요. 런처 안의 복구 흐름, 작업 로그, 실행 환경 점검을 한곳에서 볼 수 있습니다. 크레딧은 이미지 생성과 사용량 기반 도구용입니다.
Wonderful Launcher 다운로드크레딧 요금제 보기Did this fix your issue?
Your answer helps prioritize verified ComfyUI repairs.
Nunchaku 누락
ComfyUI의 ModuleNotFoundError: No module named 'nunchaku' 오류 해결 가이드. nunchaku.lora, nunchaku.utils, nunchaku.models, NunchakuFluxLoraLoader 및 NunchakuFluxDiTLoader 로드 실패 대응.
SAM 누락
Fix ModuleNotFoundError: No module named 'groundingdino' or 'segment_anything' in ComfyUI SAM, GroundingDINO, masking, and segmentation workflows.