> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-mintlify-b90d3c69.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 커스텀 노드

> ComfyUI에서 커스텀 노드 설치, 종속성 활성화, 업데이트, 비활성화, 제거에 대해 알아보세요

## 커스텀 노드 소개

ComfyUI를 설치하면 내장 노드가 많이 포함되어 있는 것을 알게 됩니다. 이러한 기본 노드는 **Comfy Core** 노드라고 하며, ComfyUI에서 공식적으로 유지 관리합니다.

또한 ComfyUI 커뮤니티의 여러 제작자가 만든 다양한 [**커스텀 노드**](https://registry.comfy.org)가 있습니다. 이 커스텀 노드는 ComfyUI에 광범위한 기능을 제공하여 그 능력과 기능의 경계를 크게 확장합니다.

이 가이드에서는 설치, 업데이트, 비활성화, 제거, 종속성 설치 등 커스텀 노드와 관련된 여러 작업을 다룹니다.

누구나 ComfyUI용 맞춤형 확장을 개발하여 다른 사람들과 공유할 수 있습니다. 많은 커뮤니티 커스텀 노드를 [여기](https://registry.comfy.org)에서 확인할 수 있습니다. 자신만의 커스텀 노드를 개발하려면 아래 섹션을 방문하여 시작하세요.

<Card title="커스텀 노드 개발 시작하기" icon="link" href="/ko/custom-nodes/overview">
  커스텀 노드 개발을 시작하는 방법 알아보기
</Card>

## 커스텀 노드 관리

이 섹션에서는 다음을 다룹니다:

* 커스텀 노드 설치
* 노드 종속성 설치
* 커스텀 노드 버전 관리
* 커스텀 노드 제거
* 커스텀 노드 일시 비활성화
* 커스텀 노드 종속성 충돌 처리

### 1. 커스텀 노드 설치

현재 ComfyUI는 다음과 같은 여러 방법을 통해 커스텀 노드 설치를 지원합니다.

* [ComfyUI Manager를 통한 설치(권장)](#install-via-comfyui-manager)
* Git을 통한 설치
* 수동 설치

**ComfyUI Manager**를 통해 커스텀 노드를 설치하는 것을 권장합니다. 이는 ComfyUI 커스텀 노드 생태계에서 매우 중요한 도구입니다. 검색, 설치, 업데이트, 비활성화, 제거 등 커스텀 노드 관리를 간단하게 만들어 줍니다. ComfyUI Manager에서 설치하려는 노드를 검색하고 설치를 클릭하기만 하면 됩니다.

그러나 현재 모든 커스텀 노드는 GitHub에 저장되어 있으므로, GitHub에 정상적으로 접근할 수 없는 지역을 위해 이 가이드에서 다양한 커스텀 노드 설치 방법에 대한 자세한 안내를 제공합니다.

또한 플러그인 관리에 **ComfyUI Manager** 사용을 권장하므로 이 도구를 플러그인 관리에 사용하는 것이 좋습니다. 소스 코드는 [여기](https://github.com/Comfy-Org/ComfyUI-Manager)에서 확인할 수 있습니다.
따라서 이 문서에서는 ComfyUI Manager 설치를 커스텀 노드 설치 예제로 사용하고, 관련 소개 섹션에서 노드 관리에 어떻게 사용하는지 보충 설명합니다.

<Tabs>
  <Tab title="ComfyUI Manager를 통한 설치">
    ComfyUI Manager는 매우 풍부한 기능을 갖추고 있으므로, 별도의 문서로 ComfyUI Manager 설치 장을 소개합니다. 아래 링크를 방문하여 ComfyUI Manager로 커스텀 노드를 설치하는 방법을 알아보세요.

    <Card title="ComfyUI Manager로 커스텀 노드 설치하기" icon="link" href="/ko/installation/install_custom_node#method-1%3A-comfyui-manager-recommended">
      ComfyUI Manager를 사용하여 커스텀 노드 설치 방법 알아보기
    </Card>
  </Tab>

  <Tab title="Git을 통한 설치">
    <Steps>
      <Step title="Git 설치 확인">
        먼저 시스템에 Git이 설치되어 있는지 확인해야 합니다. 시스템 터미널에서 다음 명령을 입력하여 Git 설치 여부를 확인할 수 있습니다.

        ```bash theme={null}
        git --version
        ```

        Git이 설치되어 있다면 다음과 유사한 출력이 표시됩니다.

        <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/custom_nodes/win_terminal.jpg?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=f20841ded5ccb31b541e64d2ce245308" alt="Windows 터미널" width="1114" height="228" data-path="images/concepts/custom_nodes/win_terminal.jpg" />

        아직 설치되지 않았다면 [git-scm.com](https://git-scm.com/)을 방문하여 해당 설치 패키지를 다운로드하세요. Linux 사용자는 [git-scm.com/downloads/linux](https://git-scm.com/downloads/linux)에서 설치 지침을 참조하세요.

        <Tip>
          Comfy Desktop 버전의 경우 아래와 같이 Desktop 터미널을 사용하여 설치를 완료할 수 있습니다.

          <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/custom_nodes/desktop_terminal.png?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=3061a529ed3231443202c3696983bc99" alt="Comfy Desktop 터미널" width="1804" height="1474" data-path="images/concepts/custom_nodes/desktop_terminal.png" />
        </Tip>
      </Step>

      <Step title="커스텀 노드 코드를 디렉터리에 복제">
        Git 설치를 완료한 후에는 커스텀 노드의 저장소 주소가 필요합니다. 여기서는 ComfyUI-Manager 저장소 주소를 예로 사용합니다.

        ```bash theme={null}
        https://github.com/Comfy-Org/ComfyUI-Manager
        ```

        <Tip>GitHub에 원활히 접근할 수 없는 지역의 경우, 다른 코드 호스팅 서비스 웹사이트를 사용하여 해당 저장소를 포크한 후 그 저장소 주소로 노드 설치를 완료할 수 있습니다 (예: gitee 등).</Tip>

        먼저 ComfyUI 커스텀 노드 디렉터리로 이동해야 합니다. ComfyUI portable 버전을 예로 들면, 폴더 위치가 `D:\ComfyUI_windows_portable`일 경우 `D:\ComfyUI_windows_portable\ComfyUI\custom_nodes`에서 커스텀 노드 폴더를 찾을 수 있습니다. 먼저 `cd` 명령을 사용하여 해당 디렉터리로 이동해야 합니다.

        ```bash theme={null}
        cd D:\ComfyUI_windows_portable\ComfyUI\custom_nodes
        ```

        그런 다음 `git clone` 명령을 사용하여 노드 설치를 완료합니다.

        ```bash theme={null}
        git clone https://github.com/Comfy-Org/ComfyUI-Manager
        ```

        모든 것이 순조롭게 진행되면 다음과 유사한 출력이 표시됩니다.

        <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/custom_nodes/install_custom_nodes_by_git.jpg?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=3b40f686e4fd7509d1aeed5a3bb27fe7" alt="Git을 통한 커스텀 노드 설치" width="1116" height="317" data-path="images/concepts/custom_nodes/install_custom_nodes_by_git.jpg" />

        이는 커스텀 노드 코드를 성공적으로 복제했음을 의미합니다. 다음으로 해당 종속성을 설치해야 합니다.
      </Step>

      <Step title="종속성 설치">
        [노드 종속성 설치](#installing-node-dependencies) 섹션의 지침을 참조하여 종속성을 설치하세요.
      </Step>
    </Steps>
  </Tab>

  <Tab title="수동 설치">
    수동 설치는 권장되는 설치 방법은 아니지만, git을 통해 원활하게 설치할 수 없는 경우를 위한 백업 옵션입니다.

    <Warning>
      이렇게 설치된 플러그인은 해당 git 버전 기록 정보를 잃게 되며, 이후 버전 관리에 불편을 초래할 수 있습니다.
    </Warning>

    <Steps>
      <Step title="커스텀 노드 코드 ZIP 패키지 다운로드">
        수동 설치를 위해서는 먼저 해당 노드 코드를 다운로드한 후 적절한 디렉터리에 압축을 풀어야 합니다.

        <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/custom_nodes/download_zip.jpg?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=268b1aacdc5b61fff12bd282055ec403" alt="노드 코드 다운로드" width="1011" height="618" data-path="images/concepts/custom_nodes/download_zip.jpg" />

        해당 커스텀 노드 저장소 페이지를 방문하세요:

        1. 'Code' 버튼을 클릭합니다.
        2. 그런 다음 'Download ZIP' 버튼을 클릭하여 ZIP 패키지를 다운로드합니다.
        3. ZIP 패키지의 압축을 풉니다.
      </Step>

      <Step title="파일을 ComfyUI 커스텀 노드 디렉터리로 복사">
        위 단계에서 압축을 푼 코드를 ComfyUI 커스텀 노드 디렉터리로 복사합니다. ComfyUI portable 버전을 예로 들면, 폴더 위치가 `D:\ComfyUI_windows_portable`일 경우 `D:\ComfyUI_windows_portable\ComfyUI\custom_nodes`에서 커스텀 노드 폴더를 찾을 수 있습니다. 위 단계에서 압축을 푼 코드를 해당 디렉터리로 복사합니다.
      </Step>

      <Step title="종속성 설치">
        [노드 종속성 설치](#installing-node-dependencies) 섹션의 지침을 참조하여 종속성을 설치하세요.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### 2. 노드 종속성 설치

커스텀 노드는 모두 관련 종속성 설치가 필요합니다. 예를 들어 ComfyUI-Manager의 경우 [requirements.txt](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/requirements.txt) 파일을 방문하여 종속성 패키지 요구 사항을 확인할 수 있습니다.

앞선 단계에서는 커스텀 노드 코드만 로컬에 복제했을 뿐 해당 종속성을 설치하지 않았으므로, 이제 해당 종속성을 설치해야 합니다.

<Note>
  실제로 ComfyUI-Manager를 사용하여 플러그인을 설치하면 ComfyUI Manager가 자동으로 종속성 설치를 완료해 줍니다. 플러그인 설치 후 ComfyUI를 다시 시작하기만 하면 됩니다. 이것이 바로 ComfyUI Manager를 사용하여 커스텀 노드를 설치하는 것을 강력히 권장하는 이유입니다.

  하지만 일부 상황에서 ComfyUI Manager를 사용하여 커스텀 노드를 원활하게 설치하지 못할 수도 있으므로, 이보다 더 자세한 종속성 설치 안내를 제공합니다.
</Note>

[종속성](/ko/development/core-concepts/dependencies) 장에서 ComfyUI의 종속성 관련 내용을 소개했습니다. ComfyUI는 **Python** 기반 프로젝트이며, ComfyUI 실행을 위해 독립적인 **Python** 런타임 환경을 구축했습니다. 모든 관련 종속성은 이 독립적인 **Python** 런타임 환경에 설치해야 합니다.

시스템 레벨 터미널에서 `pip install -r requirements.txt`를 직접 실행하면 해당 종속성이 시스템 레벨 **Python** 환경에 설치될 수 있으며, 이로 인해 ComfyUI 환경에서는 여전히 종속성이 누락되어 해당 커스텀 노드가 정상적으로 실행되지 않을 수 있습니다.

따라서 다음으로는 ComfyUI의 독립적인 Python 런타임 환경을 사용하여 종속성을 설치해야 합니다.

ComfyUI 버전에 따라 각기 다른 방법으로 해당 종속성을 설치합니다.

<Tabs>
  <Tab title="ComfyUI Portable">
    ComfyUI Portable 버전의 경우, `\ComfyUI_windows_portable\python_embeded` 디렉터리에 있는 임베디드 Python을 사용합니다. 이 Python을 사용하여 종속성 설치를 완료해야 합니다.

    먼저 portable 버전 디렉터리에서 터미널을 시작하거나, 터미널을 시작한 후 `cd` 명령을 사용하여 `\ComfyUI_windows_portable\` 디렉터리로 이동합니다.

    <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/custom_nodes/open_terminal.jpg?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=977afffc36b21104f74ef4a42e8a2334" alt="터미널 시작" width="1822" height="1187" data-path="images/concepts/custom_nodes/open_terminal.jpg" />

    터미널 디렉터리가 `\ComfyUI_windows_portable\`인지 확인합니다. 아래는 `D:\ComfyUI_windows_portable\` 예시입니다.

    <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/custom_nodes/terminal.jpg?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=167f6c1ca3ae6ddb45c8b2e8c71b1d89" alt="터미널" width="2400" height="1147" data-path="images/concepts/custom_nodes/terminal.jpg" />

    그런 다음 `python_embeded\python.exe`를 사용하여 종속성 설치를 완료합니다.

    ```bash theme={null}
    python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Manager\requirements.txt
    ```

    물론 ComfyUI-Manager 대신 실제로 설치한 커스텀 노드 이름으로 바꿀 수 있지만, 해당 노드 디렉터리에 `requirements.txt` 파일이 존재하는지 확인하세요.
  </Tab>

  <Tab title="Comfy Desktop">
    <Tip>
      Comfy Desktop 버전은 이미 설치 과정에서 ComfyUI-Manager와 그 종속성이 설치되어 있으며, 이 가이드에서도 ComfyUI Manager를 커스텀 노드 설치 예제로 사용하므로, Desktop 버전에서는 실제로 ComfyUI Manager 종속성 설치를 수행할 필요가 없습니다.
      예상치 못한 문제가 없다면, ComfyUI Manager를 사용하여 커스텀 노드를 설치하는 것을 권장하므로 수동으로 종속성을 설치할 필요가 없습니다.
    </Tip>

    <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/custom_nodes/desktop_terminal.png?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=3061a529ed3231443202c3696983bc99" alt="Comfy Desktop 터미널" width="1804" height="1474" data-path="images/concepts/custom_nodes/desktop_terminal.png" />

    그런 다음 다음 명령을 사용하여 해당 플러그인의 종속성을 설치합니다.

    ```bash theme={null}
    pip install -r .\custom_nodes\<해당_맞춤형_노드_이름>\requirements.txt
    ```

    아래는 ComfyUI-Hunyuan3Dwrapper의 종속성 설치 예시입니다.

    <img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/custom_nodes/install_dependencies.png?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=61b88e03f71ad1e312b3ddb2ccba6ed0" alt="Comfy Desktop 종속성 설치" width="1800" height="1474" data-path="images/concepts/custom_nodes/install_dependencies.png" />
  </Tab>

  <Tab title="맞춤형 Python 환경 사용자">
    맞춤형 Python 환경을 사용하는 사용자는 `pip install -r requirements.txt`를 사용하여 종속성 설치를 완료하는 것이 좋습니다.
  </Tab>
</Tabs>

### 커스텀 노드 버전 관리

커스텀 노드 버전 관리는 실제로 Git 버전 관리에 기반합니다. Git을 통해 노드 버전을 관리할 수 있지만, ComfyUI Manager는 이미 이 버전 관리 기능을 매우 잘 통합했습니다. 이렇게 편리한 도구를 제공해 주신 [@Dr.Lt.Data](https://github.com/ltdrdata)님께 깊이 감사드립니다.

이 섹션에서는 이 두 가지 다른 플러그인 버전 관리 방법을 설명드리지만, ZIP 패키지를 사용하여 수동 설치한 경우에는 해당 git 버전 기록 정보가 사라지므로 버전 관리를 수행할 수 없습니다.

<Tabs>
  <Tab title="ComfyUI Manager를 통한 버전 관리">
    <Tip>ComfyUI Manager는 지속적으로 개선 중이므로 실제 최신 인터페이스와 단계는 크게 다를 수 있습니다.</Tip>

    <Steps>
      <Step title="노드 관리 인터페이스로 진입">
        아래와 같이 해당 작업을 수행하여 ComfyUI Manager 인터페이스로 들어갑니다.
      </Step>

      <Step title="해당 커스텀 노드 패키지 찾기">
        필터를 사용하여 설치된 노드 패키지를 필터링한 후 해당 노드 관리를 수행할 수 있습니다.
      </Step>

      <Step title="버전 전환 수행">
        해당 버전으로 전환합니다. Manager가 해당 종속성 업데이트 및 설치를 도와줍니다. 일반적으로 버전 전환 후 변경 사항이 적용되려면 ComfyUI를 다시 시작해야 합니다.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Git을 통한 버전 관리">
    <Steps>
      <Step title="명령줄을 사용하여 디렉터리로 이동">
        해당 노드가 위치한 디렉터리 폴더를 찾습니다 (예: `ComfyUI/custom_nodes/ComfyUI-Manager`).
        `cd` 명령을 사용하여 해당 폴더로 이동합니다.

        ```bash theme={null}
        cd <설치_디렉터리>/ComfyUI/custom_nodes/ComfyUI-Manager
        ```
      </Step>

      <Step title="Git 명령을 사용하여 버전 확인">
        다음 명령을 사용하여 사용 가능한 모든 태그와 릴리스를 확인할 수 있습니다.

        ```bash theme={null}
        git tag
        ```

        그러면 모든 버전 태그가 나열되며, 전환하려는 버전을 선택할 수 있습니다.
      </Step>

      <Step title="지정된 버전으로 전환">
        다음 명령을 사용하여 특정 태그 또는 릴리스로 전환합니다.

        ```bash theme={null}
        git checkout <태그_이름>
        ```

        `<태그_이름>`을 전환하려는 특정 버전 태그로 바꾸세요.
      </Step>

      <Step title="특정 커밋 버전으로 전환">
        특정 커밋 버전으로 전환하려면 다음 명령을 사용하세요.

        ```bash theme={null}
        git checkout <커밋_해시>
        ```

        `<커밋_해시>`를 전환하려는 특정 커밋 해시로 바꾸세요.
      </Step>

      <Step title="종속성 설치">
        버전 전환 후 해당 커스텀 노드 패키지의 종속성이 변경될 수 있으므로 해당 노드의 종속성을 다시 설치해야 합니다. [노드 종속성 설치](#2-installing-node-dependencies) 섹션의 지침을 참조하여 해당 환경으로 이동하여 설치하세요.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### 커스텀 노드 제거

업데이트 예정

### 커스텀 노드 일시적 비활성화

업데이트 예정

### 커스텀 노드 종속성 충돌

업데이트 예정

## ComfyUI Manager

<img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/core-concepts_nodes_manager.png?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=292683b13334ed1916bfffa22d47ba8f" alt="ComfyUI Manager 인터페이스" width="1920" height="1080" data-path="images/concepts/core-concepts_nodes_manager.png" />

이 도구는 현재 [Desktop 버전](/ko/installation/desktop/windows)에 기본적으로 포함되어 있으며, [Portable 버전](/ko/installation/comfyui_portable_windows)에서는 이 문서의 [Manager 설치](#installing-custom-nodes) 섹션의 설치 지침을 참조해야 합니다.

<Note>
  ComfyUI가 계속 발전함에 따라 ComfyUI Manager가 ComfyUI에서 점점 더 중요한 역할을 하고 있습니다. 현재 ComfyUI-Manager는 공식적으로 Comfy Org 조직에 합류하여 ComfyUI의 핵심 종속성의 일부가 되었으며, 원저자인 [Dr.Lt.Data](https://github.com/ltdrdata)가 계속해서 유지 관리하고 있습니다. 자세한 내용은 [이 블로그 게시물](https://blog.comfy.org/p/comfyui-manager-joins-comfy-org)을 참조하세요.
  향후 업데이트에서 ComfyUI Manager의 사용 편의성을 크게 개선할 예정이므로, 이 문서에 표시된 인터페이스가 최신 버전의 ComfyUI Manager와 다를 수 있습니다.
</Note>

### Manager 설치

ComfyUI 서버 애플리케이션을 실행 중이라면 manager를 설치해야 합니다. ComfyUI가 실행 중이라면 계속하기 전에 종료하세요.

첫 번째 단계는 Git을 설치하는 것입니다. Git은 소프트웨어 버전 관리를 위한 명령줄 애플리케이션입니다. Git은 [github.com](https://github.com)에서 ComfyUI manager를 다운로드합니다. [git-scm.com](https://git-scm.com/)에서 Git을 다운로드하여 설치하세요.

Git 설치 후 ComfyUI 서버 프로그램 디렉터리로 이동하여 **custom\_nodes** 폴더로 들어갑니다. 명령 창이나 터미널을 엽니다. 명령줄에 현재 디렉터리 경로가 **custom\_nodes**로 표시되는지 확인합니다. 다음 명령을 실행하여 ComfyUI-Manager 저장소를 복제합니다.

```bash theme={null}
git clone https://github.com/Comfy-Org/ComfyUI-Manager.git
```

그러면 manager가 다운로드됩니다. 기술적으로 이것은 \_Git 저장소 복제\_라고 합니다.

### 누락된 노드 감지

manager를 설치한 후 manager에서 누락된 노드를 감지할 수 있습니다.

<img src="https://mintcdn.com/dripart-mintlify-b90d3c69/GOUzb1cBHEtukCGc/images/concepts/core-concepts_nodes_manager.png?fit=max&auto=format&n=GOUzb1cBHEtukCGc&q=85&s=292683b13334ed1916bfffa22d47ba8f" alt="ComfyUI Manager 인터페이스" width="1920" height="1080" data-path="images/concepts/core-concepts_nodes_manager.png" />

## 커스텀 노드 개발

개발 능력이 있다면 아래 문서부터 시작하여 커스텀 노드 개발을 시작하는 방법을 알아보세요.

<Card title="커스텀 노드 개발 시작하기" icon="link" href="/ko/custom-nodes/overview">
  커스텀 노드 개발을 시작하는 방법 알아보기
</Card>