ComfyUI 커스텀 노드 설치 방법과 충돌 해결

ComfyUI를 기본 상태로 쓰다 보면 금방 벽에 부딪힙니다. 남이 올린 워크플로를 받아왔더니 빨간 노드가 잔뜩 뜨면서 실행이 안 되고, 유튜브에서 본 그 노드는 내 화면 어디에도 없습니다.

커스텀 노드는 다른 사람이 만들어 배포한 추가 기능입니다. ComfyUI의 쓸모는 사실상 여기서 갈립니다. 다만 설치보다 어려운 게 충돌 처리라서, 이 글은 설치 방법과 함께 “설치했는데 안 보인다”, “깔았더니 멀쩡하던 게 깨졌다”를 같이 다룹니다.

ComfyUI 커스텀 노드 설치 방법 세 가지 — Manager, git clone, ZIP 다운로드 비교 — 셋 다 결과는 같습니다. `custom_nodes` 폴더에 노드 폴더가 하나 생기는 것뿐입니다.

목차 (Table of Contents)

커스텀 노드는 결국 폴더 하나입니다

설치라고 하면 복잡해 보이지만, 실제로 일어나는 일은 단순합니다. ComfyUI 설치 폴더 아래 custom_nodes 안에 폴더가 하나 생기고, ComfyUI가 시작할 때 그 폴더를 읽습니다. 실제로 쓰고 있는 PC의 custom_nodes 안은 이렇게 생겼습니다.

custom_nodes\
  ComfyUI-Manager\           168MB
  comfyui_layerstyle\         65MB
  comfyui-kjnodes\             5MB
  comfyui_essentials\
  ComfyUI-AnimateDiff-Evolved\
  ComfyUI_IPAdapter_plus\
  ComfyUI-GGUF\
  websocket_image_save.py     ← 파일 하나짜리도 있다

이 구조를 먼저 이해하면 뒤에 나오는 문제들이 전부 같은 이야기라는 게 보입니다. 안 보이면 폴더 위치가 틀렸거나 읽다가 실패한 것이고, 지우고 싶으면 폴더를 없애면 됩니다.

방법 1 — ComfyUI Manager (권장)

가장 편한 방법이고, 특별한 이유가 없으면 이쪽을 씁니다. 노드 목록에서 검색해 설치를 누르면 내려받기와 의존성 설치까지 알아서 합니다.

빨간 노드가 뜬 워크플로를 고칠 때가 특히 그렇습니다. 워크플로우 내 → 누락된 노드를 열면 지금 열려 있는 워크플로에 필요한데 없는 것만 추려 보여주고, 거기서 바로 설치하면 끝납니다. Manager 자체를 아직 안 깔았다면 ComfyUI Manager 설치와 사용법을 먼저 보시면 됩니다.

다만 Manager로도 안 되는 경우가 있는데, 그건 아래 설치가 차단될 때에서 따로 다룹니다.

방법 2 — git clone

Manager 목록에 없는 노드이거나, 특정 버전을 받아야 할 때 씁니다. custom_nodes 폴더로 이동해서 저장소를 그대로 받아옵니다.

cd ComfyUI\custom_nodes
git clone https://github.com/원저자/노드이름.git

윈도우 포터블 버전은 경로가 한 겹 더 들어갑니다.

cd ComfyUI_windows_portable\ComfyUI\custom_nodes
git clone https://github.com/원저자/노드이름.git

여기서 가장 많이 하는 실수가 ComfyUI_windows_portable 바로 아래에 clone하는 것입니다. 그 안에 ComfyUI 폴더가 한 겹 더 있고 custom_nodes는 그 안에 있습니다. 한 칸 위에 받으면 ComfyUI는 그 폴더를 아예 쳐다보지 않습니다.

git으로 받는 진짜 장점은 업데이트가 git pull 한 줄이라는 점입니다. ZIP으로 받으면 매번 다시 받아 덮어써야 합니다.

방법 3 — ZIP 다운로드

git이 없을 때 쓰는 방법입니다. GitHub 저장소에서 Code → Download ZIP으로 받아 custom_nodes 안에 풀어줍니다. 두 가지만 주의하면 됩니다.

폴더 이름 끝에 -main이 붙어 나오므로 떼어냅니다. 노드 이름을 기준으로 찾는 워크플로가 있어서 이름이 다르면 못 찾는 경우가 있습니다.
압축을 풀 때 같은 이름 폴더가 두 겹으로 겹치지 않았는지 확인합니다. 노드이름\노드이름\__init__.py 형태면 한 겹을 걷어내야 합니다.

설치 후에는 반드시 재시작

어느 방법으로 받았든 브라우저 새로고침만으로는 절대 안 나타납니다. ComfyUI는 시작할 때 한 번 custom_nodes를 읽고 끝냅니다.

ComfyUI 서버를 완전히 종료합니다 (콘솔 창에서 Ctrl+C 또는 창 닫기)
다시 실행합니다
브라우저에서 Ctrl+Shift+R로 강력 새로고침합니다

제대로 잡혔는지는 로그 한 줄로 확인합니다

“설치했는데 안 보인다”를 눈으로 찾아 헤맬 필요가 없습니다. ComfyUI는 시작할 때 읽어들인 커스텀 노드를 전부 목록으로 찍습니다. 콘솔이나 user\comfyui.log에서 Import times for custom nodes:를 찾으세요. 실제 로그입니다.

Import times for custom nodes:
   0.0 seconds: ...\custom_nodes\comfyui_essentials
   0.0 seconds (IMPORT FAILED): ...\custom_nodes\ComfyUI-MMAudio
   0.1 seconds: ...\custom_nodes\comfyui-kjnodes
   0.1 seconds: ...\custom_nodes\ComfyUI-AnimateDiff-Evolved

여기서 판정이 끝납니다.

목록에서의 모습	뜻
이름이 있고 IMPORT FAILED가 없다	정상 — 노드가 안 보이면 검색어 문제
이름 옆에 (IMPORT FAILED)	파일은 받았는데 실행에 실패
이름이 아예 없다	폴더 위치가 틀렸다

IMPORT FAILED — 가장 흔한 실패

파일은 제대로 받았는데 파이썬이 그 코드를 실행하다 죽은 상태입니다. 이유는 목록보다 위쪽에 따로 찍혀 있습니다.

File "...\custom_nodes\ComfyUI-MMAudio\nodes.py", line 5, in <module>
    from accelerate import init_empty_weights
ModuleNotFoundError: No module named 'accelerate'

Cannot import ...\custom_nodes\ComfyUI-MMAudio module for custom nodes:
No module named 'accelerate'

읽는 법은 No module named 'X'의 X가 없는 패키지이고, 그 위 File 줄이 그걸 요구한 노드입니다. 해결은 그 노드 폴더의 requirements.txt를 설치하는 것인데, ComfyUI가 쓰는 파이썬에 설치해야 합니다.

venv\Scripts\python.exe -m pip install -r custom_nodes\노드이름\requirements.txt

그냥 pip install을 치면 시스템 파이썬에 깔려서 아무 변화가 없습니다. 어느 파이썬인지는 로그 맨 위 ** Python executable: 줄에 적혀 있습니다. 이 부분을 포함해 실행이 안 될 때의 점검 순서는 ComfyUI 설치 오류 해결 모음에 따로 정리해 두었습니다.

설치가 차단될 때 — 보안 레벨

Manager에서 설치를 눌렀는데 아무 일도 안 일어나거나 거부되면, 로그에 이런 줄이 남아 있을 수 있습니다.

Blocked by policy: ...\custom_nodes\ComfyUI-Manager

커스텀 노드 설치는 남이 쓴 파이썬 코드를 내 PC에서 그대로 실행하는 일입니다. 그래서 Manager에는 보안 레벨 설정이 있고, 외부에서 접근 가능한 상태로 띄웠거나 정책이 걸려 있으면 설치를 막습니다. 설정 파일은 여기 있습니다.

ComfyUI\user\__manager\config.ini
  security_level = normal
  network_mode = public

낮추면 설치는 되지만 보안을 낮추는 선택이라는 걸 알고 바꿔야 합니다. 내 PC에서 혼자 쓰는 로컬 환경이면 몰라도, 공유 PC나 외부에서 접속 가능한 상태라면 기본값을 두는 편이 낫습니다.

충돌 — 깔았더니 멀쩡하던 게 깨졌다

ComfyUI 커스텀 노드 증상별 원인과 조치 정리표 — 증상만 보고 재설치하면 대부분 같은 자리로 돌아옵니다.

커스텀 노드는 각자 필요한 파이썬 패키지 버전을 요구하는데, 이 요구가 서로 어긋날 때 충돌이 납니다. A 노드가 어떤 라이브러리의 최신 버전을, B 노드가 예전 버전을 요구하면 나중에 설치한 쪽이 상대의 것을 덮어씁니다. 그 결과 새로 깐 노드는 되는데 잘 쓰던 노드가 죽습니다.

Manager를 쓰고 있다면 왼쪽 충돌 메뉴에 숫자 배지가 뜨고, 화면 위쪽에 “호환되지 않아 일부 확장이 비활성화되었습니다” 같은 경고가 나옵니다. 이 경고를 무시하고 설치를 밀어붙이는 것이 환경을 망가뜨리는 가장 빠른 길입니다.

이미 깨졌다면 범인부터 찾습니다. 방법은 단순합니다.

가장 최근에 설치한 노드 폴더를 custom_nodes 밖으로 옮깁니다
재시작해서 정상으로 돌아오는지 봅니다
돌아오면 그 노드가 범인입니다 — 없이 지내거나, 그 노드가 요구하는 버전에 맞춰 다시 맞춥니다

폴더를 지우지 않고 이름 뒤에 .disabled를 붙이거나 밖으로 빼내는 것만으로 비활성화가 됩니다. 되돌리기도 쉬우니 이쪽을 권합니다.

깔기 전에 확인하면 좋은 것들

ComfyUI 커스텀 노드를 설치하기 전 확인할 항목 체크리스트 — 특히 마지막 항목 — 한 번에 여러 개를 깔면 범인을 못 찾습니다.

노드를 고를 때 기준은 하나면 충분합니다. 최근에 업데이트됐고 쓰는 사람이 많은 것. Manager 카드에 다운로드 수와 마지막 업데이트 날짜가 같이 나오니 그걸 보고 고르면 됩니다. 몇 년째 손대지 않은 노드는 최신 ComfyUI에서 안 돌아가는 경우가 많고, 문제가 생겨도 검색으로 답을 찾기 어렵습니다.

용량도 한 번쯤 생각해 볼 값어치가 있습니다. 위 실제 폴더에서 보듯 Manager 하나가 168MB, 이미지 편집 노드 묶음이 65MB입니다. 여기에 노드가 따로 받아오는 모델까지 더해지면 노드만으로도 수 GB가 쌓입니다. 저장공간이 빠듯하다면 로컬 실행과 클라우드 비교도 한 번 보시면 판단에 도움이 됩니다.