ModuleNotFoundError: No module named 'nunchaku' (ComfyUI) 해결 가이드

터미널이나 시작 로그에 ModuleNotFoundError: No module named 'nunchaku', No module named 'nunchaku.lora', No module named 'nunchaku.models', NunchakuFluxLoraLoader, NunchakuFluxLoraStack 또는 NunchakuFluxDiTLoader가 표시되는 경우의 빠른 답변:

PyPI에 등록된 nunchaku라는 이름의 무관한 패키지는 설치하지 마십시오. 먼저 ComfyUI-nunchaku 확장 기능이 정상적으로 로드되었는지 확인하고, 사용 중인 Python, PyTorch, CUDA 및 GPU 사양에 맞는 공식 Nunchaku wheel 패키지를 설치해야 합니다.

2026년 7월 8일 기준 Wonderful Launcher 원격 분석 데이터에 따르면, nunchaku 가져오기 실패는 지난 30일 동안 5개의 설치 사례에서 233회의 치명적인 오류를 발생시켰습니다. nunchaku.lora, nunchaku.utils, nunchaku.merge_safetensors, 및 nunchaku.models 등 하위 모듈 에러도 동일하게 보고되었습니다.

정밀 에러 로그

터미널이나 시작 로그에 아래 에러 메시지가 출력되는 경우 본 가이드를 적용합니다.

ModuleNotFoundError: No module named 'nunchaku'
ModuleNotFoundError: No module named 'nunchaku.lora'
ModuleNotFoundError: No module named 'nunchaku.models'
Node import failed: NunchakuFluxLoraLoader

에러 발생 형태

ComfyUI 시작 시 또는 워크플로 실행 시 터미널 로그에 다음과 같이 표시됩니다.

ModuleNotFoundError: No module named 'nunchaku'

또는:

ImportError: cannot import name 'SVDQW4A4Linear'

Nunchaku FLUX 워크플로에서는 다음과 같이 붉은색 또는 누락된 노드가 표시될 수도 있습니다.

Node import failed: NunchakuFluxLoraLoader
Node import failed: NunchakuFluxLoraStack
Node import failed: NunchakuFluxDiTLoader

이 노드 에러들은 워크플로 계층에서의 결과적인 증상이며, 근본적인 원인은 ComfyUI-nunchaku 플러그인이 Nunchaku 백엔드를 제대로 가져오지 못하는 것입니다.

Nunchaku 개요

Nunchaku는 Nunchaku 팀이 개발한 SVDQuant 방법 기반의 4bit 양자화 추론 엔진입니다. ComfyUI 내에서는 대개 ComfyUI-nunchaku 확장 기능을 통해 호출되며, NVIDIA GPU 환경에서 적은 VRAM 소모로 양자화된 FLUX, Qwen-Image, SANA, PixArt 등의 모델 워크플로를 구동할 때 사용됩니다.

설치하지 않는 경우의 영향

ComfyUI 자체는 Nunchaku 없이도 정상 작동합니다. 아래 조건 중 하나 이상에 해당할 때만 Nunchaku 가속 백엔드가 요구됩니다.

• 워크플로에서 ComfyUI-nunchaku 확장 기능의 노드를 사용하는 경우
• SVDQuant/Nunchaku 양자화 모델 파일을 로드하는 경우
• 워크플로가 명시적으로 Nunchaku 로더 또는 샘플러 노드를 호출하는 경우

위의 경우가 아니라면 이 오류는 무시해도 괜찮습니다.

에러 분석 유형

PyPI 패키지명 함정 피하기

필요한 Python 모듈명이 nunchaku이지만, PyPI의 공개 패키지 중 nunchaku는 구간 선형 분할(segmental linear segmentation) 연구에 쓰이는 무관한 패키지입니다. 이를 설치해도 ComfyUI Nunchaku 오류는 해결되지 않습니다.

Nunchaku 공식 가이드에서는 우선 ComfyUI 확장 기능 플러그인을 설치한 다음, 공식 릴리스 페이지에서 백엔드 wheel을 직접 다운로드해 설치하거나 ComfyUI-nunchaku에 내장된 install_wheel.json 워크플로를 이용할 것을 권장합니다.

시스템 요구사항

Nunchaku는 아래와 같은 하드웨어/소프트웨어 호환 제한이 있습니다.

GPU 요구사항

Nunchaku는 NVIDIA GPU를 주 타깃으로 설계되었습니다. 만약 AMD, Intel, Apple Silicon 및 CPU 전용 환경을 사용 중이라면 GGUF 양자화 모델이나 더 가벼운 타 모델 워크플로로 전환하십시오.

CUDA 및 PyTorch 요구사항

Nunchaku wheel은 런타임 환경 버전과 긴밀하게 묶여 있습니다. 다음을 확인하세요.

python --version
python -c "import torch; print(torch.__version__, torch.version.cuda)"

Windows 포터블 버전인 경우:

.\python_embeded\python.exe -s --version
.\python_embeded\python.exe -s -c "import torch; print(torch.__version__, torch.version.cuda)"

이 정보들과 완벽히 조화되는 wheel 버전을 찾아야 합니다.

설치 방법

방법 1: ComfyUI-nunchaku 설치 프로그램 워크플로 사용

최신 ComfyUI-nunchaku 플러그인을 설치했다면, 내장된 install_wheel.json 워크플로를 이용하는 것이 권장됩니다.

1. ComfyUI 내로 install_wheel.json 워크플로 파일을 드래그해 로드합니다.
2. 설치 프로그램 노드를 update node 모드로 실행해 이용 가능한 최신 버전 목록을 갱신합니다.
3. 본인 시스템의 Python, PyTorch, CUDA, GPU 사양에 매칭되는 wheel을 고릅니다.
4. 노드를 install 모드로 설정해 실행합니다.
5. ComfyUI 서버를 완전히 종료 후 재시작합니다.

방법 2: 호환되는 wheel 패키지 수동 설치

공식 배포 경로에서 whl 파일을 다운로드합니다.

• GitHub Releases: https://github.com/nunchaku-tech/nunchaku/releases
• Hugging Face organization: https://huggingface.co/nunchaku-tech

ComfyUI를 실행 중인 Python 환경을 통해 설치를 명령합니다.

python -m pip install <whl파일_로컬경로_또는_다운로드URL>

Windows 포터블 버전인 경우:

.\python_embeded\python.exe -s -m pip install <whl파일_로컬경로_또는_다운로드URL>

방법 3: 소스 코드 직접 빌드

Windows 환경에서 Nunchaku를 직접 빌드하려면 호환되는 CUDA 툴킷, Visual Studio/MSVC 및 빌드 개발 환경의 온전한 세팅이 요구됩니다. 일반 사용자에게는 사전 빌드된 whl 패키지 사용이 권장됩니다.

자주 발생하는 실패 유형

"No matching distribution found"

사용 중인 Python/PyTorch/CUDA 버전에 매치되는 whl 파일이 릴리스 목록에 존재하지 않는 경우입니다. 환경 버전을 다시 파악하세요.

오인된 패키지 설치

PyPI에서 이름만 같은 무관한 nunchaku 패키지를 설치했다면 먼저 언설치해야 에러가 해결됩니다.

python -m pip uninstall nunchaku -y

그 다음 공식 Nunchaku wheel 패키지를 재설치합니다.

로컬 디렉토리 이름 충돌

현재 활성 디렉토리에 nunchaku라는 폴더가 위치하면 Python이 라이브러리 대신 이 로컬 폴더를 가져오려고 시도합니다. ComfyUI 루트 및 하위 경로에 이름이 겹치는 폴더가 없는지 검토하세요.

whl 설치 성공 후에도 노드가 여전히 붉은색으로 표시됨

import nunchaku 명령은 에러 없이 성공하지만 노드가 여전히 누락 상태인 경우, 플러그인 모듈 로드 중 다른 의존성 충돌이나 파일 유실이 일어났을 수 있습니다. 아래 엔드포인트 응답 정보 또는 시작 로그를 확인하세요.

http://127.0.0.1:8188/v2/customnode/import_fail_info_bulk

설치 검증

아래 명령을 터미널에 넣어 확인합니다.

python -c "import nunchaku; print(getattr(nunchaku, '__version__', 'installed'))"

이후 ComfyUI를 재시작하고 노드가 정상 로드되는지 관찰하세요.

관련 가이드

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

출처 참조

• ComfyUI-nunchaku GitHub 리포지토리
• Nunchaku 공식 가이드 페이지
• Nunchaku GitHub Releases