> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# pyproject.toml

# 사양

`pyproject.toml` 파일에는 ComfyUI 커스텀 노드를 위한 두 가지 주요 섹션이 포함되어 있습니다: `[project]`와 `[tool.comfy]`. 아래는 각 섹션의 사양입니다.

## \[project] 섹션

### name (필수)

노드 ID는 커스텀 노드를 고유하게 식별하며, 레지스트리의 URL에서 사용됩니다. 사용자는 이 이름을 참조하여 노드를 설치할 수 있습니다:

```bash theme={null}
comfy node install <node-id>
```

**요구사항:**

* 100자 미만이어야 합니다.
* 알파벳과 숫자, 하이픈, 밑줄, 점만 포함할 수 있습니다.
* 연속된 특수 문자를 포함할 수 없습니다.
* 숫자나 특수 문자로 시작할 수 없습니다.
* 대소문자를 구분하지 않습니다.

**모범 사례:**

* 짧고 설명적인 이름을 사용하세요.
* 이름에 "ComfyUI"를 포함하지 마세요.
* 기억하기 쉽고 입력하기 편한 이름을 지정하세요.

**예시:**

```toml theme={null}
name = "image-processor"      # ✅ 좋음: 간단하고 명확함
name = "super-resolution"     # ✅ 좋음: 기능을 설명함
name = "ComfyUI-enhancer"    # ❌ 나쁨: ComfyUI를 포함함
name = "123-tool"            # ❌ 나쁨: 숫자로 시작함
```

자세한 내용은 공식 [파이썬 문서](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#name)를 참조하세요.

### version (필수)

[semantic versioning](https://semver.org/)을 사용하며, X.Y.Z 세 자리 버전 번호를 사용합니다:

* X (**MAJOR**): 중대한 변경사항
* Y (**MINOR**): 새로운 기능 (하위 호환성 유지)
* Z (**PATCH**): 버그 수정

**예시:**

```toml theme={null}
version = "1.0.0"    # 초기 릴리스
version = "1.1.0"    # 새로운 기능 추가
version = "1.1.1"    # 버그 수정
version = "2.0.0"    # 중대한 변경사항
```

### license (선택적)

커스텀 노드의 라이선스를 지정합니다. 두 가지 방식으로 지정할 수 있습니다:

1. **파일 참조:**

```toml theme={null}
license = { file = "LICENSE" }     # ✅ LICENSE 파일을 가리킴
license = { file = "LICENSE.txt" } # ✅ LICENSE.txt를 가리킴
license = "LICENSE"                # ❌ 형식 오류
```

2. **라이선스 이름:**

```toml theme={null}
license = { text = "MIT License" }  # ✅ 올바른 형식
license = { text = "Apache-2.0" }   # ✅ 올바른 형식
license = "MIT LICENSE"             # ❌ 형식 오류
```

공통 라이선스: [MIT](https://opensource.org/license/mit), [GPL](https://www.gnu.org/licenses/gpl-3.0.en.html), [Apache](https://www.apache.org/licenses/LICENSE-2.0)

### description (권장)

커스텀 노드가 하는 일을 간략히 설명합니다.

```toml theme={null}
description = "이미지 품질을 향상시키기 위한 초해상도 노드"
```

### repository (필수)

관련 자료로 연결합니다:

```toml theme={null}
[project.urls]
Repository = "https://github.com/username/repository"
```

### urls (권장)

관련 자료로 연결합니다:

```toml theme={null}
[project.urls]
Documentation = "https://github.com/username/repository/wiki"
"Bug Tracker" = "https://github.com/username/repository/issues"
```

### requires-python (권장)

노드가 지원하는 파이썬 버전을 지정합니다:

```toml theme={null}
requires-python = ">=3.8"        # 파이썬 3.8 이상
requires-python = ">=3.8,<3.11"  # 파이썬 3.8부터 3.11까지
```

### 프론트엔드 버전 호환성 (선택적)

노드가 특정 ComfyUI 프론트엔드 버전을 요구하는 경우, `comfyui-frontend-package` 종속성을 사용해 이를 지정할 수 있습니다. 이 패키지는 [PyPI](https://pypi.org/project/comfyui-frontend-package/)에 게시됩니다.

예를 들어 다음 경우에 이 필드를 사용하세요:

* 커스텀 노드가 특정 버전에서 도입된 프론트엔드 API를 사용하는 경우
* 노드와 특정 프론트엔드 버전 간의 호환성 문제가 발견된 경우
* 노드가 최신 프론트엔드 버전에서만 제공되는 특정 UI 기능을 필요로 하는 경우

```toml theme={null}
[project]
dependencies = [
    "comfyui-frontend-package>=1.20.0"       # 프론트엔드 1.20.0 이상 필요
    "comfyui-frontend-package<=1.21.6"       # 프론트엔드 1.21.6까지 제한
    "comfyui-frontend-package>=1.19,<1.22"   # 1.19부터 1.21.x까지 작동
    "comfyui-frontend-package~=1.20.0"       # 1.20.x와 호환되지만 1.21.0은 아님
    "comfyui-frontend-package!=1.21.3"       # 1.21.3을 제외한 모든 버전과 작동
]
```

### classifiers (권장)

운영체제 호환성 및 GPU 가속기를 지정하기 위해 classifier를 사용합니다. 이 정보는 사용자가 자신의 시스템에 적합한 노드를 찾도록 돕습니다.

```toml theme={null}
[project]
classifiers = [
    # 운영체제 독립형 노드 (모든 운영체제에서 작동)
    "Operating System :: OS Independent",

    # 또는 운영체제별 노드의 경우, 지원되는 시스템을 지정하세요:
    "Operating System :: Microsoft :: Windows",  # 윈도우 전용
    "Operating System :: POSIX :: Linux",  # 리눅스 전용
    "Operating System :: MacOS",  # 맥OS 전용
    
    # GPU 가속기 지원
    "Environment :: GPU :: NVIDIA CUDA",    # NVIDIA CUDA 지원
    "Environment :: GPU :: AMD ROCm",       # AMD ROCm 지원
    "Environment :: GPU :: Intel Arc",      # 인텔 아크 지원
    "Environment :: NPU :: Huawei Ascend",  # 화웨이 아센드 지원
    "Environment :: GPU :: Apple Metal",    # 애플 메탈 지원
]
```

## \[tool.comfy] 섹션

### PublisherId (필수)

고유한 출판사 식별자로, 일반적으로 GitHub 사용자명과 일치합니다.

**예시:**

```toml theme={null}
PublisherId = "john-doe"        # ✅ GitHub 사용자명과 일치
PublisherId = "image-wizard"    # ✅ 고유한 식별자
```

### DisplayName (선택적)

커스텀 노드의 사용자 친화적인 이름입니다.

```toml theme={null}
DisplayName = "초해상도 노드"
```

### Icon (선택적)

ComfyUI 레지스트리와 ComfyUI-Manager에 표시될 커스텀 노드 아이콘의 URL입니다.

**요구사항:**

* 파일 형식: SVG, PNG, JPG, GIF
* 최대 해상도: 400px × 400px
* 종횡비는 정사각형이어야 합니다.

```toml theme={null}
Icon = "https://raw.githubusercontent.com/username/repo/main/icon.png"
```

### Banner (선택적)

ComfyUI 레지스트리와 ComfyUI-Manager에 표시될 큰 배너 이미지의 URL입니다.

**요구사항:**

* 파일 형식: SVG, PNG, JPG, GIF
* 종횡비: 21:9

```toml theme={null}
Banner = "https://raw.githubusercontent.com/username/repo/main/banner.png"
```

### requires-comfyui (선택적)

노드가 호환되는 ComfyUI 버전을 지정합니다. 사용자가 올바른 ComfyUI 버전을 설치했는지 확인하도록 돕습니다.

**지원 연산자:** `<`, `>`, `<=`, `>=`, `~=`, `<>`, `!=` 및 범위

```toml theme={null}
requires-comfyui = ">=1.0.0"        # ComfyUI 1.0.0 이상
requires-comfyui = ">=1.0.0,<2.0.0"  # ComfyUI 1.0.0부터 2.0.0까지
requires-comfyui = "~=1.0.0"         # 호환 가능한 릴리스: 1.0.0 이상이지만 2.0.0은 아님
requires-comfyui = "!=1.2.3"         # 1.2.3을 제외한 모든 버전
requires-comfyui = ">0.1.3,<1.0.0"   # 0.1.3보다 크고 1.0.0보다 작은 버전
```

### includes (선택적)

특정 폴더를 강제로 포함할지 여부를 지정합니다. 일부 상황에서는 프론트엔드 프로젝트의 커스텀 노드와 같이 최종 패키징 출력 폴더가 .gitignore에 포함될 수 있습니다. 이런 경우 레지스트리 사용을 위해 강제로 포함해야 합니다.

```toml theme={null}
includes = ['dist']
```

<Tip>게시된 아카이브에서 파일을 제외하려면(‘includes’의 반대), 게시 페이지의 [`.comfyignore`](/ko/registry/publishing#exclude-files-with-comfyignore)를 참조하세요.</Tip>

## 전체 예시

```toml theme={null}
[project]
name = "super-resolution-node"
version = "1.0.0"
description = "고급 초해상도 기법을 사용해 이미지 품질을 향상시킵니다"
license = { file = "LICENSE" }
requires-python = ">=3.8"
dependencies = [
    "comfyui-frontend-package<=1.21.6"  # 프론트엔드 버전 호환성
]
classifiers = [
    "Operating System :: OS Independent"  # 모든 운영체제에서 작동
]
dynamic = ["dependencies"]

[tool.setuptools.dynamic]
dependencies = {file = ["requirements.txt"]}

[project.urls]
Repository = "https://github.com/username/super-resolution-node"
Documentation = "https://github.com/username/super-resolution-node/wiki"
"Bug Tracker" = "https://github.com/username/super-resolution-node/issues"

[tool.comfy]
PublisherId = "image-wizard"
DisplayName = "Super Resolution Node"
Icon = "https://raw.githubusercontent.com/username/super-resolution-node/main/icon.png"
Banner = "https://raw.githubusercontent.com/username/super-resolution-node/main/banner.png"
requires-comfyui = ">=1.0.0"  # ComfyUI 버전 호환성
```