comfyui-nodes

ComfyUI Custom Node Development Skill

Comprehensive guide to creating custom nodes for ComfyUI. Covers both the current V1 API and the new V3 schema API.

Quick Reference

Official Resources:

• Repository: https://github.com/comfyanonymous/ComfyUI
• Documentation: https://docs.comfy.org/custom-nodes
• V3 Migration: https://docs.comfy.org/custom-nodes/v3_migration
• Example Nodes: https://github.com/comfyanonymous/ComfyUI/tree/master/comfy_extras

---

File Structure

Custom nodes go in ComfyUI/custom_nodes/:

ComfyUI/
└── custom_nodes/
    └── my_custom_nodes/
        ├── __init__.py          # REQUIRED: Node registration
        ├── nodes.py             # Node class definitions
        ├── requirements.txt     # Optional: pip dependencies
        └── web/                 # Optional: Frontend JS extensions
            └── js/
                └── my_extension.js

---

Basic Node Template

ALL FOUR class attributes (CATEGORY, RETURN_TYPES, FUNCTION, INPUT_TYPES) are REQUIRED. Missing any one will cause silent failure.

class MyCustomNode:
    """Description of what this node does."""

    # ── ALL FOUR REQUIRED ATTRIBUTES ──────────────────────────
    CATEGORY = "my_nodes/utilities"       # REQUIRED: Menu location
    RETURN_TYPES = ("IMAGE",)             # REQUIRED: Output types as TUPLE (NOT a method!)
    RETURN_NAMES = ("output_image",)      # Optional: Display names for outputs
    FUNCTION = "process"                  # REQUIRED: Name of the method ComfyUI will call
    OUTPUT_NODE = False                   # Optional: True for terminal nodes (save, preview)
    # ──────────────────────────────────────────────────────────

    @classmethod
    def INPUT_TYPES(cls):                 # REQUIRED: Must be a @classmethod
        return {
            "required": {
                "image": ("IMAGE",),
                "strength": ("FLOAT", {
                    "default": 1.0,
                    "min": 0.0,
                    "max": 2.0,
                    "step": 0.1,
                    "display": "slider",
                    "tooltip": "Effect strength"
                }),
            },
            "optional": {
                "mask": ("MASK",),
            },
            "hidden": {
                "node_id": "UNIQUE_ID",
            }
        }

    # Method name MUST match FUNCTION value. Parameters MUST match INPUT_TYPES keys.
    # Do NOT use execute(**kwargs). Use explicit named parameters.
    def process(self, image, strength, mask=None, node_id=None):
        # Your processing logic here
        result = image * strength
        return (result,)  # MUST return a tuple matching RETURN_TYPES (NOT a dict!)