ComfyUI 커스텀 노드 requirements.txt 미설치 에러 해결법
requirements.txt 의존성 라이브러리가 올바른 Python 환경에 설치되지 않아 실행이 차단된 ComfyUI 커스텀 노드 복구 가이드.
커뮤니티 정보
본 가이드의 내용은 일반적인 ComfyUI 문제 해결 패턴을 기반으로 하며, 모든 개별 사용자 환경에서 테스트를 거친 것은 아닙니다. 패키지 설치/변경 작업을 시작하기 전에 가상환경이나 포터블 폴더를 백업해 두는 것을 권장합니다.
ComfyUI 서버 구동 시 특정 커스텀 노드에 IMPORT FAILED 경고가 발생하며 상세 로그에 ModuleNotFoundError가 표시되는 경우, 가장 주된 원인은 해당 커스텀 노드용 requirements.txt 패키지 설치 단계를 누락했기 때문입니다.
커스텀 노드 리포지토리를 custom_nodes/ 경로에 Git 클론하거나 다운로드해 압축을 푸는 것은 소스 코드만 배치한 단계입니다. 이 코드들이 가져다 쓰는 Python 패키지는 별도로 활성 Python 환경에 설치해 주어야 합니다.
2026년 6월 29일까지의 30일간 Wonderful Launcher 원격 분석 데이터에 따르면, 커스텀 노드 의존성 누락 이슈는 지속적으로 빈번하게 발생하고 있습니다. 사용자의 노드 유실 경고, 클론 시도, 의존성 설치 실패, 그리고 최종 ModuleNotFoundError로 이어지는 련의 과정을 개별 이슈가 아닌 하나의 복원 경로 체인으로 다루는 것이 좋습니다.
빠른 해결책
GitHub Standalone Windows 포터블 버전을 사용하는 경우:
.\python_embeded\python.exe -s -m pip install -r ComfyUI\custom_nodes\<node-name>\requirements.txt
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build설치 전에 반드시 requirements.txt 내용을 검토해 시스템 충돌을 유발할 수 있는 패키지 설정이 있는지 파악하세요.
구체적인 에러 현상
IMPORT FAILED: ComfyUI-ExampleNode
Traceback (most recent call last):
File "...\custom_nodes\ComfyUI-ExampleNode\__init__.py", line 4, in <module>
import somepackage
ModuleNotFoundError: No module named 'somepackage'노드 폴더는 custom_nodes/에 온전히 존재하지만, 내부 코드 실행에 필요한 somepackage 라이브러리가 미설치되어 가져오기(Import)에 실패한 양상입니다.
주로 누락되는 에러 모듈 유형
아래 라이브러리들은 지원 로그에서 특히 누락 빈도가 높게 관측되는 대표적 모듈입니다. 해당 노드를 다시 설치하거나 지우기 전에 아래 항목을 먼저 체크해 보세요.
| 누락 모듈 | 주요 연관 워크플로 | 최우선 검증 사항 |
|---|---|---|
triton | 가속 연산, SageAttention, 동영상/LLM | 설치 전에 이 패키지가 필수 사양인지 단순 경고 플래그인지 파악 |
sageattention | Wan/동영상 가속 및 attention 강제 플래그 | 가속 기능이 필수가 아니라면 시작 명령 인자에서 제거 |
onnx / onnxruntime | 얼굴 교체, DWPose 자세 검출, IPAdapter, ReActor | 속도 최적화가 무관하다면 CPU 버전 onnxruntime을 우선 고려 |
llama_cpp | GGUF 텍스트 처리, 로컬 LLM 구동 노드 | 설치 시 실제 패키지명은 llama-cpp-python입니다. |
nunchaku | Nunchaku Quantization FLUX/Qwen 가속 | PyPI의 무관한 표준 nunchaku 패키지를 설치하지 마세요. |
sox / decord | 오디오 및 비디오 처리 보조 노드 | 덮어놓고 깔기 전에 노드 소스 코드에서 실제 필수인지 확인 |
groundingdino / segment_anything | 객체 검출, 마스크 분할 세그멘테이션 | SAM/GroundingDINO 설치 가이드 참조 |
dlib / nvvfx | 페이스/비디오 특수 효과 | OS 및 C++ 빌드 환경 호환성이 중요하므로 노드 README 정독 |
여기에 없는 패키지라도 기본 원리는 같습니다. 에러를 뱉는 커스텀 노드를 먼저 파악한 다음, 필요한 의존 패키지를 ComfyUI 전용 Python 환경 경로에 선별적으로 수동 설치해 주는 것입니다.
원인 분석
- Git 클론만 하고 pip install 생략: 소스 코드 폴더만 가져오고 의존 라이브러리 설치 단계를 생략함
- ComfyUI Manager 설치 실패: 매니저가 노드를 클론해 올렸으나 라이브러리 설치 과정에서 내부적으로 실패함
- 환경 초기화: ComfyUI를 재설치하거나 포터블 버전을 새로 다운받아 기존 설치 패키지들이 덮어써짐
- 엉뚱한 Python 경로에 설치: 패키지를 메인 Windows OS Python에 설치해 ComfyUI 내장 Python에 반영 안 됨
- requirements.txt 부재: 일부 소형 커스텀 노드는 텍스트 파일 없이 README 설명란에만 라이브러리 이름을 명시해 둠
단계별 복구 절차
1단계: 실패한 노드 이름 식별
ComfyUI 서버 터미널 시작 로그에서 IMPORT FAILED 라인을 확인하세요. 작동이 멈춘 노드 경로명과 누락된 모듈명이 적혀 있습니다.
2단계: requirements.txt 파일 존재 확인
다음 명령 등을 활용해 파일이 있는지 경로를 확인합니다.
dir ComfyUI\custom_nodes\<node-name>\requirements.txt파일이 있다면 3단계로 가고, 없다면 해당 노드의 깃허브 README 페이지로 이동해 의존 패키지 관련 수동 안내를 읽어야 합니다.
3단계: 설치 전에 파일 내용 검토
다음 명령을 통해requirements 파일의 내용을 먼저 출력해 봅니다.
type ComfyUI\custom_nodes\<node-name>\requirements.txt아래와 같은 항목이 있다면 주의가 필요합니다:
| 포함된 내용 | 발생할 수 있는 위험 |
|---|---|
torch, torchvision, torchaudio | 현재 구성된 CUDA PyTorch 가속 환경이 CPU 전용 깡통 버전으로 덮어써질 위험 |
버전 범위 미지정 (== 이나 >= 등의 규격 없음) | 호환되지 않는 최신 패키지가 임의로 설치되어 타 노드 충돌 유발 |
opencv-python-headless 상태에서 opencv-python 설치 요구 | OpenCV DLL 간의 충돌로 인한 실행 차단 |
| 너무 오래되었거나 과도하게 새로운 특정 버전 고정 | 타 커스텀 노드들과의 버전 대치로 연쇄 에러 유발 |
파일 내용이 안전하다면 4단계를 진행합니다. 만약 torch나 핵심 무거운 패키지가 명시되어 있다면 전체 설치 대신 유실된 특정 패키지만 개별적으로 수동 설치하는 것이 좋습니다.
4단계: 의존성 패키지 설치
Windows 포터블 버전인 경우:
.\python_embeded\python.exe -s -m pip install -r ComfyUI\custom_nodes\<node-name>\requirements.txt수동 가상 환경(venv)인 경우:
python -m pip install -r custom_nodes/<node-name>/requirements.txt5단계: 개별적 수동 설치 (안전함)
전체 의존성 목록을 다 올렸을 때의 시스템 손상을 피하기 위해, 실제 유실 모듈만 짚어서 수동 설치합니다.
.\python_embeded\python.exe -s -m pip install somepackage특히 requirements 파일에 torch 등이 대거 기재되어 있어 시스템 환경 덮어쓰기가 우려되는 경우에 매우 유용합니다.
6단계: 검증
ComfyUI 서버를 다시 켜고 터미널에서 IMPORT FAILED 문구가 사라졌는지 관찰합니다.
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build관련 가이드
출처 참조
실제 ComfyUI 환경에서 생긴 문제라면 먼저 무료로 Wonderful Launcher 로 현재 머신을 확인하세요. 런처 안의 복구 흐름, 작업 로그, 실행 환경 점검을 한곳에서 볼 수 있습니다. 크레딧은 이미지 생성과 사용량 기반 도구용입니다.
Wonderful Launcher 다운로드크레딧 요금제 보기Did this fix your issue?
Your answer helps prioritize verified ComfyUI repairs.