9 skills covering ComfyUI custom node development with the V3 and V1 APIs

GitHub stars
319

Install

/plugin install comfyui-custom-nodes@comfyui-custom-node-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add jtydhr88/comfyui-custom-node-skills.

Contents

Discovered from source

Skills 9

ComfyUI Advanced Node Patterns (V3)

V3 provides advanced input patterns for dynamic, type-safe, and flexible node designs.

MatchType - Generic Type Connections

MatchType ensures that inputs and outputs sharing a template have the same type at connection time. Like generics in typed languages.

class PassThrough(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        # Template(template_id, allowed_types=AnyType) - optional type constraint
        template = io.MatchType.Template("T")
        return io.Schema(
            node_id="PassThrough",
            display_name="Pass Through",
            category="utils",
            inputs=[
                io.MatchType.Input("value", template=template),
            ],
            outputs=[
                io.MatchType.Output(template=template, display_name="output"),
            ],
        )

    @classmethod
    def execute(cls, value):
        return io.NodeOutput(value)

When the user connects an IMAGE to the input, the output automatically becomes IMAGE type.

Switch Node Pattern

Core Switch (since v0.35) makes both branches optional so either may be left disconnected. A disconnected optional input is absent from kwargs; a connected-but-unevaluated lazy input is None. Use a sentinel to tell them apart:

MISSING = object()

class Switch(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        template = io.MatchType.Template("switch")
        return io.Schema(
            node_id="Switch",
            display_name="Switch",
            category="logic",
            inputs=[
                io.Boolean.Input("switch"),
                io.MatchType.Input("on_false", template=template, lazy=True, optional=True),
                io.MatchType.Input("on_true", template=template, lazy=True, optional=True),
            ],
            outputs=[
                io.MatchType.Output(template=template, display_name="output"),
            ],
        )

    @classmethod
    def check_lazy_status(cls, switch, on_false=MISSING, on_true=MISSING):
        if switch and on_true is None:      # connected, not yet evaluated
            return ["on_true"]
        if not switch and on_false is None:
            return ["on_false"]

    @classmethod
    def execute(cls, switch, on_true=MISSING, on_false=MISSING):
        selected = on_true if switch else on_false
        return io.NodeOutput(None if selected is MISSING else selected)

MultiType - Accept Multiple Types

A single input that accepts several different types:

io.MultiType.Input("data",
    types=[io.Image, io.Mask, io.Latent],
    optional=True,
)

Autogrow - Dynamic Growing Inputs

Inputs that automatically add more slots as the user connects to them. Two template modes:

TemplatePrefix (numbered slots)

class ConcatImages(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ConcatImages",
            display_name="Concat Images",
            category="image",
            inputs=[
                io.Autogrow.Input("images",
                    template=io.Autogrow.TemplatePrefix(
                        input=io.Image.Input("img"),  # template for each slot
                        prefix="image_",              # slot names: image_0, image_1, ...
                        min=2,                        # minimum visible slots (default 1)
                        max=16,                       # maximum slots (default 10, hard limit 100)
                    ),
                ),
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def execute(cls, images: io.Autogrow.Type):
        # images is a dict: {"image_0": tensor, "image_1": tensor, ...}
        tensors = [v for v in images.values() if v is not None]
        return io.NodeOutput(torch.cat(tensors, dim=0))

TemplateNames (named slots)

io.Autogrow.Input("inputs",
    template=io.Autogrow.TemplateNames(
        input=io.Float.Input("val"),
        names=["red", "green", "blue", "alpha"],  # specific slot names
        min=3,  # first 3 are required
    ),
)
# Creates slots: "red" (required), "green" (required), "blue" (required), "alpha" (optional)

Key behaviors:

  • Widget inputs in template are forced to connection-only (force_input=True)
  • Slots below min are required; above min are optional
  • Maximum 100 names total

DynamicCombo - Conditional Inputs

A combo dropdown where each option reveals different sub-inputs:

class ProcessNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ProcessNode",
            display_name="Process Node",
            category="processing",
            is_output_node=True,
            inputs=[
                io.DynamicCombo.Input("mode", options=[
                    io.DynamicCombo.Option("resize", [
                        io.Int.Input("width", default=512, min=1, max=8192),
                        io.Int.Input("height", default=512, min=1, max=8192),
                    ]),
                    io.DynamicCombo.Option("blur", [
                        io.Float.Input("radius", default=5.0, min=0.1, max=100.0),
                    ]),
                    io.DynamicCombo.Option("sharpen", [
                        io.Float.Input("amount", default=1.0, min=0.0, max=10.0),
                    ]),
                ]),
                io.Image.Input("image"),
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def execute(cls, mode: io.DynamicCombo.Type, image, **kwargs):
        # mode is a dict with the combo value + sub-inputs
        # key for selected option matches the DynamicCombo input ID
        if mode["mode"] == "resize":
            width = mode["width"]
            height = mode["height"]
            # ... resize logic
        return io.NodeOutput(image)

Nested DynamicCombo:

io.DynamicCombo.Input("outer", options=[
    io.DynamicCombo.Option("option1", [
        io.DynamicCombo.Input("inner", options=[
            io.DynamicCombo.Option("sub1", [io.Float.Input("val")]),
            io.DynamicCombo.Option("sub2", [io.Int.Input("count")]),
        ])
    ]),
])

DynamicSlot - Connection-Triggered Inputs

Like DynamicCombo, but sub-inputs are revealed when a connection is made to the slot instead of when a combo option is selected:

io.DynamicSlot.Input(
    slot=io.Image.Input("image"),        # the trigger slot (widget inputs are forced to connection-only)
    inputs=[                              # revealed when the slot is connected
        io.Float.Input("blend", default=0.5),
        io.Boolean.Input("invert", default=False),
    ],
)
# Value type: dict containing the slot value + sub-input values

Note: DynamicSlot is registered infrastructure in comfy_api.latest but is not yet used by any core node; treat it as experimental.

_DynamicGroup (COMFY_DYNAMICGROUP_V3, a repeated row of widgets, used by core LoRA stack nodes) is internal and unstable: it is not exported from io; do not import it from comfy_api.latest._io. Frontend support arrived in frontend v1.57.0.

Lazy Inputs Inside Dynamic Inputs

Sub-inputs of Autogrow / DynamicCombo can be lazy=True (scheduling fixed in v0.40). In check_lazy_status only, every nested value arrives as a (value, original_key) tuple; return the original_key to request it. execute receives plain values.

io.Autogrow.Input("rows", template=io.Autogrow.TemplatePrefix(
    io.Image.Input("img", lazy=True), prefix="item", min=1))

@classmethod
def check_lazy_status(cls, rows):
    value, key = rows["item0"]          # key == "rows.item0"
    return [key] if value is None else []

Loops (core StartLoop / EndLoop)

Since v0.36 core ships StartLoop / EndLoop (utilities/looping; simple / For / List modes, carried value, accumulate). Prefer them over custom loop nodes. Things that affect authors:

  • The loop body is cloned per iteration via node expansion, so nodes inside a loop run once per iteration and cls.hidden.unique_id is an expanded id (display id maps back to the original node).
  • io.Schema(loop_boundary="start" | "end") marks loop boundaries for prompt validation (pairing, no escaping body, accumulate not fed from the body). It is tied to the core loop implementation; treat as experimental.

Node Expansion - Subgraph Injection

Nodes can return a subgraph that replaces themselves during execution:

from comfy_execution.graph_utils import GraphBuilder

class RepeatNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="RepeatNode",
            display_name="Repeat KSampler",
            category="sampling",
            enable_expand=True,
            inputs=[
                io.Model.Input("model"),
                io.Int.Input("repeat_count", default=2, min=1, max=10),
                io.Latent.Input("latent"),
            ],
            outputs=[io.Latent.Output("LATENT")],
        )

    @classmethod
    def execute(cls, model, repeat_count, latent):
        graph = GraphBuilder()
        current_latent = latent
        for i in range(repeat_count):
            sampler = graph.node("KSampler",
                model=model,
                latent_image=current_latent,
                # ... other params
            )
            current_latent = sampler.out(0)
        return io.NodeOutput(current_latent, expand=graph.finalize())

Key rules for node expansion:

  • Set enable_expand=True in Schema
  • Use GraphBuilder to construct subgraphs safely
  • Return io.NodeOutput(output_ref, expand=graph.finalize())
  • Node IDs in subgraph must be deterministic and unique
  • Each subnode is cached separately

Accept All Inputs

Accept arbitrary inputs not defined in the schema:

class FlexibleNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="FlexibleNode",
            display_name="Flexible Node",
            category="utils",
            accept_all_inputs=True,
            inputs=[io.Combo.Input("mode", options=["a", "b"])],
            outputs=[io.String.Output()],
        )

    @classmethod
    def validate_inputs(cls, mode, **kwargs):
        return True  # skip validation for dynamic inputs

    @classmethod
    def execute(cls, mode, **kwargs):
        # kwargs contains all dynamic inputs
        return io.NodeOutput(str(kwargs))

Execution Blocking

Prevent downstream execution conditionally:

class GateNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="GateNode",
            display_name="Gate",
            category="logic",
            inputs=[
                io.Boolean.Input("allow"),
                io.Image.Input("image"),
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def execute(cls, allow, image):
        if not allow:
            return io.NodeOutput(block_execution="Gate is closed")
        return io.NodeOutput(image)

Async Execute

V3 natively supports async execution:

class AsyncNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="AsyncNode",
            display_name="Async Node",
            category="utils",
            inputs=[io.String.Input("url")],
            outputs=[io.String.Output()],
        )

    @classmethod
    async def execute(cls, url):
        import aiohttp
        async with aiohttp.ClientSession() as session:
            async with session.get(url) as response:
                text = await response.text()
        return io.NodeOutput(text)

Progress Reporting

Report progress during long operations:

from comfy_api.latest import ComfyAPISync  # sync version; use ComfyAPI + await for async execute

class SlowNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="SlowNode",
            display_name="Slow Node",
            category="utils",
            inputs=[io.Int.Input("steps", default=100)],
            outputs=[io.String.Output()],
        )

    @classmethod
    def execute(cls, steps):
        api = ComfyAPISync()
        for i in range(steps):
            # ... do work ...
            api.execution.set_progress(i + 1, steps)
        return io.NodeOutput("done")

NodeReplace - Migration Between Nodes

Register replacements so old workflows auto-migrate to new nodes:

from typing_extensions import override
from comfy_api.latest import ComfyAPI, ComfyExtension, io

class MyExtension(ComfyExtension):
    @override
    async def on_load(self):
        api = ComfyAPI()
        await api.node_replacement.register(io.NodeReplace(
            new_node_id="MyNewNode_v2",
            old_node_id="MyOldNode",
            old_widget_ids=["width", "height", "mode"],  # positional widget order
            input_mapping=[
                {"new_id": "image_in", "old_id": "image"},     # rename input
                {"new_id": "size", "set_value": 512},           # set fixed value
            ],
            output_mapping=[
                {"new_idx": 0, "old_idx": 0},       # index-based, not name-based
            ],
        ))

    @override
    async def get_node_list(self):
        return [MyNewNodeV2]

InputMap types:

  • InputMapOldId: {"new_id": str, "old_id": str} — map old input to new
  • InputMapSetValue: {"new_id": str, "set_value": Any} — set fixed value on new
  • Dot notation for autogrow inputs: {"new_id": "images.image0", "old_id": "image1"}

OutputMap (index-based, not name-based):

  • {"new_idx": int, "old_idx": int} — map old output index to new

old_widget_ids: Required because workflow JSON stores widget values by position, not by ID. This list maps positional indexes to input IDs for correct migration.

ComfyAPI - Runtime API

from comfy_api.latest import ComfyAPI, ComfyAPISync

# In sync execute(): use ComfyAPISync (no await)
api = ComfyAPISync()
api.execution.set_progress(value=50, max_value=100)
api.execution.set_progress(
    value=50, max_value=100,
    node_id=None,                   # optional: defaults to current node
    preview_image=pil_image,        # PIL Image or ImageInput tensor
    ignore_size_limit=False,
)

# In async execute(): use ComfyAPI (with await)
api = ComfyAPI()
await api.execution.set_progress(value=50, max_value=100)

# Node replacement registration (in async on_load)
await api.node_replacement.register(io.NodeReplace(...))

See Also

  • comfyui-node-basics - Node fundamentals
  • comfyui-node-inputs - Basic input types
  • comfyui-node-lifecycle - Execution lifecycle and caching
  • comfyui-node-outputs - Output types and UI helpers

ComfyUI Custom Node Basics (V3 API)

ComfyUI uses Python classes to define nodes. The V3 API is the current recommended approach. Nodes inherit from io.ComfyNode and define a schema + execute method.

Quick Start

from comfy_api.latest import ComfyExtension, io

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode",
            display_name="My Custom Node",
            category="my_category",
            inputs=[
                io.Image.Input("image"),
                io.Float.Input("strength", default=1.0, min=0.0, max=1.0, step=0.01),
            ],
            outputs=[
                io.Image.Output("IMAGE"),
            ],
        )

    @classmethod
    def execute(cls, image, strength):
        result = image * strength
        return io.NodeOutput(result)

V3 Node Class Structure

Every V3 node requires:

  1. Inherit from io.ComfyNode
  2. define_schema(cls) - classmethod returning io.Schema
  3. execute(cls, ...) - classmethod performing the computation
from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

class ImageBrighten(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ImageBrighten",          # unique identifier
            display_name="Brighten Image",     # shown in UI
            category="image/adjust",           # menu path
            description="Adjusts image brightness",
            inputs=[
                io.Image.Input("image"),
                io.Float.Input("factor", default=1.2, min=0.0, max=3.0, step=0.1),
            ],
            outputs=[
                io.Image.Output("IMAGE"),
            ],
        )

    @classmethod
    def execute(cls, image, factor):
        result = torch.clamp(image * factor, 0.0, 1.0)
        return io.NodeOutput(result)

io.Schema Fields

io.Schema(
    node_id="UniqueNodeID",            # required: unique string ID
    display_name="Display Name",        # optional: shown in UI menus
    category="category/subcategory",    # menu hierarchy (default "sd")
    description="Node description",     # optional: tooltip text
    inputs=[...],                       # list of Input objects
    outputs=[...],                      # list of Output objects
    hidden=[...],                       # list of Hidden enum values
    is_output_node=False,               # True for nodes with side effects (save, preview)
    is_experimental=False,              # marks as experimental
    is_deprecated=False,                # marks as deprecated
    is_dev_only=False,                  # hidden unless dev mode enabled
    is_api_node=False,                  # marks as API-only node
    is_input_list=False,                # receive full lists instead of individual items
    not_idempotent=False,               # no cache sharing between identical instances (see lifecycle)
    accept_all_inputs=False,            # accept arbitrary inputs via **kwargs
    enable_expand=False,                # allow node expansion (subgraphs)
    search_aliases=["alias1", "alias2"],# alternative search terms
    essentials_category="Basic",        # optional: Essentials tab category
    price_badge=None,                   # optional: PriceBadge for API nodes
    has_intermediate_output=False,      # True for nodes with interactive UI that produce intermediate outputs
    loop_boundary=None,                 # "start"/"end": core loop validation (v0.36+, experimental)
)

V3 Node Registration

V3 nodes are registered via ComfyExtension and comfy_entrypoint():

from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode",
            display_name="My Node",
            category="my_nodes",
            inputs=[io.String.Input("text", multiline=True)],
            outputs=[io.String.Output()],
        )

    @classmethod
    def execute(cls, text):
        return io.NodeOutput(text.upper())


class MyExtension(ComfyExtension):
    @override
    async def get_node_list(self) -> list[type[io.ComfyNode]]:
        return [MyNode]


async def comfy_entrypoint() -> MyExtension:
    return MyExtension()

The comfy_entrypoint() function must be defined at the module level (in the file directly imported by ComfyUI).

V1 Node Structure (Legacy Reference)

V1 nodes use class attributes and NODE_CLASS_MAPPINGS:

class MyNodeV1:
    CATEGORY = "my_category"
    FUNCTION = "execute"
    RETURN_TYPES = ("IMAGE",)
    RETURN_NAMES = ("image",)

    @classmethod
    def INPUT_TYPES(s):
        return {
            "required": {
                "image": ("IMAGE",),
                "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0}),
            }
        }

    def execute(self, image, strength):
        return (image * strength,)

NODE_CLASS_MAPPINGS = {"MyNodeV1": MyNodeV1}
NODE_DISPLAY_NAME_MAPPINGS = {"MyNodeV1": "My Node V1"}

Key Differences: V3 vs V1

AspectV3V1
Base classio.ComfyNodePlain class
Execute methodexecute classmethod (fixed name)Instance method (custom name via FUNCTION)
Inputsio.Schema(inputs=[...])INPUT_TYPES() dict
Outputsio.Schema(outputs=[...])RETURN_TYPES tuple
Return valueio.NodeOutput(...)Plain tuple
RegistrationComfyExtension + comfy_entrypoint()NODE_CLASS_MAPPINGS dict
StateNo instance state (classmethods)Instance state allowed
Hidden inputscls.hidden.prompt, etc.kwargs from "hidden" dict

Important Rules

  • node_id must be globally unique across all nodes
  • execute() parameters must match input IDs exactly
  • All methods are @classmethod in V3 (no instance state)
  • Return io.NodeOutput(val1, val2, ...) matching output count
  • Category uses / separator for hierarchy: "image/transform"
  • Prefix category with _ to hide from menus: "_for_testing"

See Also

  • comfyui-node-datatypes - Data types (IMAGE, LATENT, MASK, etc.)
  • comfyui-node-inputs - Input configuration details
  • comfyui-node-outputs - Output types and UI outputs
  • comfyui-node-packaging - Project structure and packaging
  • comfyui-node-lifecycle - Execution lifecycle and caching

ComfyUI Data Types

ComfyUI uses specific data types for node inputs and outputs. Understanding tensor shapes and data formats is essential.

Complete Type Reference

Tensor/Data Types

TypeV3 ClassFormatDescription
IMAGEio.Imagetorch.Tensor [B,H,W,C] float32 0-1Batch of RGB images
MASKio.Masktorch.Tensor [H,W] or [B,H,W] float32 0-1Grayscale masks
LATENTio.Latent{"samples": Tensor[B,C,H,W] or [B,C,T,H,W], "noise_mask"?: Tensor, "batch_index"?: list[int], "type"?: str}Latent space (4D image / 5D video)
CONDITIONINGio.Conditioninglist[tuple[Tensor, PooledDict]]Text conditioning with pooled outputs
AUDIOio.Audio{"waveform": Tensor[B,C,T], "sample_rate": int}Audio data
VIDEOio.VideoVideoInput ABCVideo data (abstract base class)
SIGMASio.Sigmastorch.Tensor 1D, length steps+1Noise schedule
NOISEio.NoiseObject with generate_noise()Noise generator
LORA_MODELio.LoraModeldict[str, torch.Tensor]LoRA weight deltas
LOSS_MAPio.LossMap{"loss": list[torch.Tensor]}Loss map
TRACKSio.Tracks{"track_path": Tensor, "track_visibility": Tensor}Motion tracking data
WAN_CAMERA_EMBEDDINGio.WanCameraEmbeddingtorch.TensorWAN camera embeddings
LATENT_OPERATIONio.LatentOperationCallable[[Tensor], Tensor]Latent transform function
TIMESTEPS_RANGEio.TimestepsRangetuple[int, int]Range 0.0-1.0
DICTio.DictdictGeneric dictionary
ARRAYio.ArraylistGeneric list/array
LAYERSio.Layers{"version": int, "canvas"?: (w, h), "layers": list[LayerItem]}Layer stack (v0.31+); LayerItem: image tensor, type: "raster", z_index, optional x, y, mask, name, opacity, blend_mode (io.Layers.BlendMode), visible, flip_h/v, rotation, w, h

Model Types (opaque, typically pass-through)

TypeV3 ClassPython Type
MODELio.ModelModelPatcher
CLIPio.ClipCLIP
VAEio.VaeVAE
CONTROL_NETio.ControlNetControlNet
CLIP_VISIONio.ClipVisionClipVisionModel
CLIP_VISION_OUTPUTio.ClipVisionOutputClipVisionOutput
STYLE_MODELio.StyleModelStyleModel
GLIGENio.GligenModelPatcher (wrapping Gligen)
UPSCALE_MODELio.UpscaleModelImageModelDescriptor
BACKGROUND_REMOVALio.BackgroundRemovalBackgroundRemovalModel (e.g. BiRefNet)
LATENT_UPSCALE_MODELio.LatentUpscaleModelAny
SAMPLERio.SamplerSampler
GUIDERio.GuiderCFGGuider
HOOKSio.HooksHookGroup
HOOK_KEYFRAMESio.HookKeyframesHookKeyframeGroup
MODEL_PATCHio.ModelPatchAny
AUDIO_ENCODERio.AudioEncoderAny
AUDIO_ENCODER_OUTPUTio.AudioEncoderOutputAny
PHOTOMAKERio.PhotomakerAny
POINTio.PointAny
FACE_ANALYSISio.FaceAnalysisAny
BBOXio.BBOXAny
SEGSio.SEGSAny

3D Types

TypeV3 ClassPython TypeDescription
MESHio.MeshMESH(vertices, faces)3D mesh with vertices + faces tensors
VOXELio.VoxelVOXEL(data)Voxel data tensor
SPLATio.SplatSPLATGaussian splat data
FILE_3Dio.File3DAnyFile3DAny supported 3D format
FILE_3D_GLBio.File3DGLBFile3DBinary glTF
FILE_3D_GLTFio.File3DGLTFFile3DJSON-based glTF
FILE_3D_FBXio.File3DFBXFile3DFBX format
FILE_3D_OBJio.File3DOBJFile3DOBJ format
FILE_3D_STLio.File3DSTLFile3DSTL format (3D printing)
FILE_3D_USDZio.File3DUSDZFile3DApple AR format
FILE_3D_PLYio.File3DPLYFile3DPLY (point cloud / splat)
FILE_3D_SPLATio.File3DSPLATFile3D.splat gaussian splat file
FILE_3D_SPZio.File3DSPZFile3DCompressed splat (.spz)
FILE_3D_KSPLATio.File3DKSPLATFile3D.ksplat format
FILE_3D_SPLAT_ANYio.File3DSplatAnyFile3DAny splat format
FILE_3D_POINT_CLOUD_ANYio.File3DPointCloudAnyFile3DAny point cloud format
SVGio.SVGSVGScalable vector graphics
LOAD_3Dio.Load3DModel3DDict (see below)3D model with renders
LOAD_3D_ANIMATIONio.Load3DAnimationSame as Load3DAnimated 3D model
LOAD3D_CAMERAio.Load3DCameraCameraInfo (see below)3D camera info
LOAD3D_MODEL_INFOio.Load3DModelInfolist[Model3DTransform]Per-model transforms (position/quaternion/scale)

Load3D.Model3DDict: {"image": str, "mask": str, "normal": str, "camera_info": CameraInfo, "recording"?: str, "model_3d_info"?: list[Model3DTransform]}

Load3DCamera.CameraInfo (right-handed, Y-up, camera looks down -Z): required keys position, target, zoom, cameraType ('perspective' | 'orthographic'); optional keys quaternion (camera world rotation), useCustomUp (bool, v0.40+: use the quaternion's up instead of world +Y), fov (vertical, degrees, perspective only), aspect, near, far, frustum (orthographic only: {left, right, top, bottom}).

Load3DModelInfo.Model3DTransform: {"position": dict, "quaternion": dict, "scale": dict} in world space.

Widget Types (create UI controls)

TypeV3 ClassPython TypeDescription
INTio.IntintInteger with min/max/step
FLOATio.FloatfloatFloat with min/max/step/round
STRINGio.StringstrText (single/multi-line)
BOOLEANio.BooleanboolToggle with labels
COMBOio.CombostrDropdown selection
COMBO (multi)io.MultiCombolist[str]Multi-select dropdown
COLORio.Colorstr (hex)Color picker, default #ffffff
COLORSio.Colorslist[str] (hex)Color palette (list of colors)
BOUNDING_BOXio.BoundingBox{"x": int, "y": int, "width": int, "height": int}Rectangle region
BOUNDING_BOXESio.BoundingBoxeslist[{"x", "y", "width", "height", "metadata": dict}]Multiple labeled regions
CURVEio.Curvelist[tuple[float, float]]Spline curve points
RANGEio.RangeRangeInput (min/max + optional midpoint)Levels/range editor with gradient display
IMAGECOMPAREio.ImageComparedictImage comparison widget
WEBCAMio.WebcamstrWebcam capture widget
HISTOGRAMio.Histogramlist[int]Histogram bin counts
VIDEO_EDITio.VideoEdit{"trim"?: {start_time, duration}, "crop"?: {x, y, width, height}}Video trim/crop editor (features=["trim","crop"])
RESOLUTION_PREVIEWio.ResolutionPreviewdictLive resolution preview bound to other widgets by name
COMPOSITORio.Compositordict (LayerState)Layer-editor state, default {}
CAMERA_INFO_STATEio.CameraInfoStatedictCamera editor state (input only)

Special Types

TypeV3 ClassDescription
* (ANY)io.AnyTypeMatches any type
COMFY_MULTITYPED_V3io.MultiTypeAccept multiple specific types on one input
COMFY_MATCHTYPE_V3io.MatchTypeGeneric type matching across inputs/outputs
COMFY_AUTOGROW_V3io.AutogrowDynamic growing inputs
COMFY_DYNAMICCOMBO_V3io.DynamicComboCombo that reveals sub-inputs per option
COMFY_DYNAMICSLOT_V3io.DynamicSlotConnection slot that reveals sub-inputs when connected (not yet used by core nodes)
COMFY_DYNAMICGROUP_V3(internal _DynamicGroup)Repeated widget rows; not exported, unstable — do not use (frontend support since v1.57.0)
FLOW_CONTROLio.FlowControlInternal testing only
ACCUMULATIONio.AccumulationInternal testing only

IMAGE Type

Images are torch.Tensor with shape [B, H, W, C]:

  • B = batch size (1 for single image)
  • H = height in pixels
  • W = width in pixels
  • C = channels (3 for RGB, values 0.0-1.0)
import torch
import numpy as np
from PIL import Image as PILImage

class ImageProcessor(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ImageProcessor",
            display_name="Image Processor",
            category="image",
            inputs=[io.Image.Input("image")],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def execute(cls, image):
        b, h, w, c = image.shape
        result = torch.clamp(image * 1.5, 0.0, 1.0)
        return io.NodeOutput(result)

Loading / Saving Images

from PIL import ImageOps

# Load from file → tensor
def load_image(path):
    img = PILImage.open(path)
    img = ImageOps.exif_transpose(img)   # fix rotation from camera EXIF
    if img.mode == "I":                  # handle 16-bit images
        img = img.point(lambda i: i * (1 / 255))
    img = img.convert("RGB")
    return torch.from_numpy(np.array(img).astype(np.float32) / 255.0).unsqueeze(0)

# Tensor → save to file
def save_image(tensor, path):
    if tensor.dim() == 4:
        tensor = tensor[0]
    PILImage.fromarray(np.clip(255.0 * tensor.cpu().numpy(), 0, 255).astype(np.uint8)).save(path)

# Batch operations
batch = torch.cat([img1, img2], dim=0)    # stack into batch
single = image[i]                          # extract from batch [H,W,C]
single_batch = image.unsqueeze(0)          # add batch dim [1,H,W,C]

MASK Type

torch.Tensor with shape [H, W] or [B, H, W], values 0.0-1.0.

# Invert mask
inverted = 1.0 - mask

# Mask ↔ Image conversion
alpha = mask.unsqueeze(0).unsqueeze(-1)                   # [1,H,W,1]
gray_mask = 0.299*img[:,:,:,0] + 0.587*img[:,:,:,1] + 0.114*img[:,:,:,2]
image_from_mask = mask.unsqueeze(-1).repeat(1, 1, 1, 3)  # [B,H,W,3]

# Ensure batch dim
if mask.dim() == 2:
    mask = mask.unsqueeze(0)  # [1, H, W]

LATENT Type

Dict with typed keys:

class LatentDict(TypedDict):
    samples: torch.Tensor       # [B, C, H, W] (image) or [B, C, T, H, W] (video) - required
    noise_mask: NotRequired[torch.Tensor]
    batch_index: NotRequired[list[int]]
    type: NotRequired[str]      # only for "audio", "hunyuan3dv2"

Image models (SD1.5, SDXL, SD3, Flux): 4D [B, C, H, W] — SD1.5/SDXL = 4 channels, SD3/Flux = 16 channels. Latent dimensions are 1/8 of pixel dims.

Video models (Hunyuan Video, Wan, Cosmos, LTX Video, Mochi): 5D [B, C, T, H, W] — T is the temporal (frame) dimension.

samples = latent["samples"]
# Check dimensionality:
if samples.ndim == 5:
    B, C, T, H, W = samples.shape   # video latent
else:
    B, C, H, W = samples.shape      # image latent

# Always preserve extra keys when modifying:
result = latent.copy()
result["samples"] = modified_samples

CONDITIONING Type

list[tuple[Tensor, PooledDict]] — a list of (cond_tensor, metadata_dict) pairs.

The PooledDict contains many optional keys for different models:

class PooledDict(TypedDict):
    pooled_output: torch.Tensor
    control: NotRequired[ControlNet]
    area: NotRequired[tuple[int, ...]]
    strength: NotRequired[float]           # default 1.0
    mask: NotRequired[torch.Tensor]
    start_percent: NotRequired[float]      # 0.0-1.0
    end_percent: NotRequired[float]        # 0.0-1.0
    guidance: NotRequired[float]           # Flux-like models
    hooks: NotRequired[HookGroup]
    # ... many more model-specific keys (SDXL, SVD, WAN, etc.)

Combine conditioning: result = cond_a + cond_b (list concatenation).

VIDEO Type

VideoInput is an abstract base class with methods:

class VideoInput(ABC):
    def get_components(self) -> VideoComponents    # images tensor + audio + frame_rate
    def save_to(self, path, format=VideoContainer.AUTO, codec=VideoCodec.AUTO, metadata=None,
                bit_depth=None,     # None keeps native depth
                crf=None,           # H.264/AV1 CRF; None -> 18 (H.264) / 24 (AV1)
                color_space=None,   # "sRGB" | "HDR" (BT.2020 HLG) | "HDR PQ"
                preset=None)        # H.264 encoder preset, e.g. "ultrafast"
    def as_trimmed(self, start_time=None, duration=None, strict_duration=False) -> VideoInput | None
    def as_cropped(self, x=0, y=0, width=0, height=0) -> VideoInput  # clamped, even-aligned; empty/full rect = self
    def get_stream_source(self) -> str | BytesIO
    def get_dimensions(self) -> tuple[int, int]     # (width, height)
    def get_duration(self) -> float                  # seconds
    def get_frame_count(self) -> int
    def get_frame_rate(self) -> Fraction
    def get_container_format(self) -> str
    def get_bit_depth(self) -> int                   # max component bits of the stream, e.g. 8/10/12 (default 8)
    def get_color_space(self) -> str                 # "sRGB" | "HDR" | "HDR PQ" | "auto" (unknown)

High bit depth and HDR (v0.34+) are supported end-to-end: loaders report get_bit_depth() / get_color_space(), save nodes preserve them. Codecs: Types.VideoCodec.AUTO/H264/AV1; containers: Types.VideoContainer.AUTO/MP4/MKV/WEBM.

Concrete implementations (via from comfy_api.latest import InputImpl):

  • VideoFromFile(file, *, start_time=0, duration=0, crop=None) — path or BytesIO; crop=(x, y, w, h)
  • VideoFromComponents(components, bit_depth=8, color_space="sRGB") — from tensors
  • VideoFromList(videos, complete_audio=None, codec=AUTO) — concatenation (v0.36+)

3D Types

File3D

from comfy_api.latest import Types

# File3D wraps a 3D file (disk path or BytesIO stream)
file_3d = Types.File3D(source="/path/to/model.glb", file_format="glb")
file_3d.format              # "glb"
file_3d.is_disk_backed      # True
file_3d.get_data()          # BytesIO
file_3d.get_bytes()         # raw bytes
file_3d.save_to("/output/model.glb")

MESH, VOXEL and SPLAT

from comfy_api.latest import Types

mesh = Types.MESH(vertices=torch.tensor(...), faces=torch.tensor(...))  # (B,N,3), (B,M,3)
voxel = Types.VOXEL(data=torch.tensor(...), voxel_colors=None, resolution=None)
splat = Types.SPLAT(...)   # gaussian splat data

MESH optional fields (pass by keyword — metallic_roughness was inserted before vertex_counts in v0.34, breaking positional calls): uvs (B,N,2), vertex_colors (B,N,3|4), texture (B,H,W,3 baseColor), metallic_roughness (B,H,W,3; G=roughness, B=metallic), vertex_counts/face_counts (B,) real lengths for padded batches (both or neither), unlit, normals (B,N,3), tangents (B,N,4), normal_map, occlusion_in_mr, material (dict), emissive.

Widget Types with Special Features

Color

io.Color.Input("color", default="#ff0000", socketless=True)
# Value is a hex string like "#ff0000"

Colors (palette)

io.Colors.Input("palette", default=["#ff0000", "#00ff00"], socketless=True)
# Value is list[str] of hex colors

BoundingBox

io.BoundingBox.Input("bbox",
    default={"x": 0, "y": 0, "width": 512, "height": 512},
    socketless=True,
    component="my_component",  # optional custom UI component
)
# Value is {"x": int, "y": int, "width": int, "height": int}

BoundingBoxes (multiple regions)

io.BoundingBoxes.Input("regions", default=[], socketless=True)
# Value is list of {"x": int, "y": int, "width": int, "height": int, "metadata": dict}

Curve

from comfy_api.input import CurveInput

io.Curve.Input("curve",
    default=[(0.0, 0.0), (1.0, 1.0)],  # linear
    socketless=True,
)
# In execute(), normalize the raw value first:
curve = CurveInput.from_raw(curve)

Range (levels editor)

from comfy_api.input import RangeInput

io.Range.Input("levels",
    default={"min": 0.0, "max": 1.0},
    display=None,                # widget visualization mode
    gradient_stops=None,         # gradient background for the slider
    show_midpoint=True,          # show gamma midpoint handle
    midpoint_scale=None,
    value_min=0.0, value_max=1.0,  # UI bounds
)
# In execute(), normalize with RangeInput.from_raw(value):
# .min_val, .max_val, .midpoint (gamma = -log2(midpoint), 0.5 = linear)
# .to_lut(size) generates a GIMP-style levels lookup table

MultiCombo

io.MultiCombo.Input("tags",
    options=["tag1", "tag2", "tag3"],
    default=["tag1"],
    placeholder="Select tags...",
    chip=True,  # show as chips
)
# Value is list[str]

Webcam

io.Webcam.Input("webcam_capture")
# Value is str (captured image data)

ImageCompare

io.ImageCompare.Input("comparison", socketless=True)
# Value is dict

Custom Types

# Simple: create inline custom type
MyData = io.Custom("MY_DATA_TYPE")

# Use in inputs/outputs
io.Schema(
    inputs=[MyData.Input("data")],
    outputs=[MyData.Output("MY_DATA")],
)

Advanced: @comfytype decorator

For custom types with type hints or custom Input/Output classes:

from comfy_api.latest._io import comfytype, ComfyTypeIO

@comfytype(io_type="MY_DATA_TYPE")
class MyData(ComfyTypeIO):
    Type = dict[str, Any]  # type hint for the data

RAM cache sizing: the default RAM-pressure cache measures CPU tensors in outputs (also inside lists/tuples/dicts); opaque objects count as a small default. For a custom class holding large tensors, add def _comfy_cache_tensors(self): return (self.a, self.b) (as core MESH/VOXEL/SPLAT do, v0.35+) so it is sized and evicted correctly.

AnyType / Wildcard

# Accept any single type (always a connection input, no widget)
io.AnyType.Input("anything")

# Accept specific multiple types
io.MultiType.Input("data", types=[io.Image, io.Mask, io.Latent])

# MultiType with widget override (shows widget for first type)
io.MultiType.Input(
    io.Float.Input("value", default=1.0),
    types=[io.Float, io.Int],
)

Imports from comfy_api.latest

from comfy_api.latest import (
    ComfyExtension,  # extension registration
    ComfyAPI,        # runtime API (progress, node replacement)
    io,              # all io types (io.Image, io.Schema, io.ComfyNode, etc.)
    ui,              # UI output helpers (ui.PreviewImage, ui.SavedImages, etc.)
    Input,           # Input.Image (ImageInput), Input.Audio, Input.Mask, Input.Latent, Input.Video
    InputImpl,       # InputImpl.VideoFromFile, .VideoFromComponents, .VideoFromList
    Types,           # Types.MESH, Types.VOXEL, Types.File3D, Types.VideoCodec, etc.
)

Tensor Safety

When checking if a tensor exists, always use is not None instead of truthiness:

# CORRECT
if image is not None:
    process(image)

# WRONG — multi-element tensors don't support bool()
if image:       # raises RuntimeError
    process(image)

# For boolean conditions on tensors, use .all() or .any()
if (mask > 0.5).all():
    ...

Type Conversion Patterns

# IMAGE [B,H,W,C] → MASK [B,H,W]
mask = 0.299 * image[:,:,:,0] + 0.587 * image[:,:,:,1] + 0.114 * image[:,:,:,2]

# MASK [B,H,W] → IMAGE [B,H,W,C]
image = mask.unsqueeze(-1).repeat(1, 1, 1, 3)

# Resize image tensor
import torch.nn.functional as F
resized = F.interpolate(
    image.permute(0, 3, 1, 2),  # [B,C,H,W] for interpolate
    size=(new_h, new_w), mode='bilinear', align_corners=False
).permute(0, 2, 3, 1)  # back to [B,H,W,C]

See Also

  • comfyui-node-basics - Node class structure and registration
  • comfyui-node-inputs - Input configuration details (widget options)
  • comfyui-node-outputs - Output types and UI outputs
  • comfyui-node-advanced - MatchType, MultiType, Autogrow, DynamicCombo

ComfyUI Frontend Extensions

Custom nodes can extend the ComfyUI frontend with JavaScript. Extensions register hooks, widgets, commands, settings, and UI components.

Quick Start

1. Export WEB_DIRECTORY in Python

# __init__.py
WEB_DIRECTORY = "./js"
__all__ = ["WEB_DIRECTORY"]

2. Create JavaScript Extension

// js/my_extension.js
import { app } from "../../scripts/app.js";

app.registerExtension({
    name: "my_nodes.my_extension",

    async setup() {
        console.log("Extension loaded!");
    },
});

All .js files in WEB_DIRECTORY are loaded automatically when ComfyUI starts.

Extension Hooks (Lifecycle Order)

init — After canvas created, before nodes

app.registerExtension({
    name: "my.ext",
    async init(app) {
        // Modify core behavior, add global listeners
    },
});

addCustomNodeDefs — Modify node definitions

async addCustomNodeDefs(defs, app) {
    // defs is a dict of all node definitions
    // Can add or modify definitions before registration
    defs["MyFrontendNode"] = {
        input: { required: { text: ["STRING", {}] } },
        output: ["STRING"],
        output_name: ["text"],
        name: "MyFrontendNode",
        display_name: "My Frontend Node",
        category: "custom",
    };
},

getCustomWidgets — Register custom widget types

getCustomWidgets(app) {
    return {
        MY_WIDGET(node, inputName, inputData, app) {
            const widget = node.addWidget("text", inputName, "", () => {});
            widget.serializeValue = () => widget.value;
            return { widget };  // or { widget, minWidth, minHeight }; v1.54+ also accepts `return widget`
        },
    };
},

beforeRegisterNodeDef — Modify node prototype

async beforeRegisterNodeDef(nodeType, nodeData, app) {
    if (nodeData.name === "MyNode") {
        // Chain onto prototype methods
        const origOnCreated = nodeType.prototype.onNodeCreated;
        nodeType.prototype.onNodeCreated = function () {
            origOnCreated?.apply(this, arguments);
            // Add custom widget, modify behavior, etc.
            this.addWidget("button", "Run", null, () => {
                console.log("Button clicked!");
            });
        };
    }
},

nodeCreated — After node instance created

nodeCreated(node, app) {
    if (node.comfyClass === "MyNode") {
        // Modify this specific node instance
        node.color = "#335";
    }
},

setup — After app fully loaded

async setup(app) {
    // Add event listeners, register UI components
    app.api.addEventListener("executed", (event) => {
        console.log("Node executed:", event.detail);
    });
},

loadedGraphNode — When loading saved graph

loadedGraphNode(node, app) {
    if (node.comfyClass === "MyNode") {
        // Restore state from saved graph
    }
},

registerCustomNodes — Register additional node types

registerCustomNodes(app) {
    // Register custom LiteGraph node types
},

beforeRegisterVueAppNodeDefs — Modify node defs before Vue registration

beforeRegisterVueAppNodeDefs(defs, app) {
    // Modify definitions before they reach the Vue app
},

beforeConfigureGraph / afterConfigureGraph

async beforeConfigureGraph(graphData, missingNodeTypes, app) {
    // Before graph data is applied
},
async afterConfigureGraph(missingNodeTypes, app) {
    // After graph is fully configured
},

beforeLoadGraph / afterLoadGraph (v1.53.5+) / onGraphLoadError (v1.54.2+)

Bracket a whole workflow load (including API-JSON and A1111 imports, which skip beforeConfigureGraph). Order: beforeLoadGraph → beforeConfigureGraph → afterConfigureGraph → afterLoadGraph; onGraphLoadError runs instead of the after* hooks when the load fails.

beforeLoadGraph(app) { /* e.g. suspend your own listeners */ },
afterLoadGraph(app) { /* graph fully loaded */ },
onGraphLoadError(error, app) { /* undo whatever beforeLoadGraph started */ },

Upcoming (unreleased): graph loads are queued, and calling app.loadGraphData() / loadApiJson() / handleFile() from inside any graph-load hook rejects ("cannot start a nested graph load"). Defer it (setTimeout) if you must load another graph.

getSelectionToolboxCommands — Add commands to selection toolbox

getSelectionToolboxCommands(selectedItem) {
    // Return array of command IDs to show when item is selected
    return ["my.ext.doSomething"];
},

onNodeOutputsUpdated — Execution outputs changed

onNodeOutputsUpdated(nodeOutputs) {
    // nodeOutputs: Record<NodeLocatorId, output data>, fired when node outputs update
},

Authentication Hooks

onAuthUserResolved(user, app) {
    // Fires when user authentication resolves
},
onAuthTokenRefreshed() {
    // Fires when auth token is refreshed
},
onAuthUserLogout() {
    // Fires when user logs out
},

Custom Widgets

Adding DOM Widgets

beforeRegisterNodeDef(nodeType, nodeData, app) {
    if (nodeData.name === "MyNode") {
        const origOnCreated = nodeType.prototype.onNodeCreated;
        nodeType.prototype.onNodeCreated = function () {
            origOnCreated?.apply(this, arguments);

            const container = document.createElement("div");
            container.innerHTML = `<input type="color" value="#ff0000">`;
            container.querySelector("input").addEventListener("change", (e) => {
                this.widgets.find(w => w.name === "color").value = e.target.value;
            });

            this.addDOMWidget("colorPicker", "custom", container, {
                serialize: true,
                getValue() { return container.querySelector("input").value; },
                setValue(v) { container.querySelector("input").value = v; },
            });
        };
    }
},

Widget Hooks

// Called before prompt is queued
// isPartialExecution is true when only selected nodes are queued
widget.beforeQueued = function ({ isPartialExecution } = {}) {
    // Prepare widget value
};

// Called after prompt is queued
widget.afterQueued = function ({ isPartialExecution } = {}) {
    // Reset or update widget. Core control_after_generate now also applies
    // on partial runs (v1.53.5+); the flag is still passed for your own logic.
};

// Custom serialization (may be async; it is awaited)
widget.serializeValue = function (node, index) {
    return JSON.stringify(this.value);
};

Widget Rules (store-backed widgets, v1.53+)

Widget values live in a store keyed by graphId:nodeId:widgetName:

  • Names must be unique per node. A repeat is renamed to name#1, name#2… or refused if it cannot be renamed (v1.58+); before that it silently overwrote the first widget's value.
  • Don't rename a widget after adding it — the stored value stays under the old name. Remove it and add a new one.
  • Remove with node.removeWidget(widget), not by splicing node.widgets.
  • node.widgets may be undefined until first assigned: node.widgets ??= [], node.widgets?.length ?? 0.
  • Create widgets via addWidget / addCustomWidget / addDOMWidget (or a BaseWidget subclass). A plain object pushed onto node.widgets is never registered.

Hiding Widgets

widget.hidden = true;            // hide everywhere at runtime (still serialized; works in Nodes 2.0)
widget.advanced = true;          // show only when "show advanced" is on

// Per-surface policy at creation (v1.55.6+); all three keys are required
node.addWidget("text", "debug", "", null, {
    surfaces: { canvas: "shown", vueNode: "never", panel: "never" },  // "shown" | "advanced" | "never"
});

options.canvasOnly (= vueNode/panel: "never") is deprecated but still honored; options.hideInPanel hides only from the right side panel.

Declarative Extension Properties

Commands

app.registerExtension({
    name: "my.ext",
    commands: [
        {
            id: "my.ext.doSomething",
            label: "Do Something",
            icon: "pi pi-bolt",
            function: () => { console.log("Executed!"); },
            // v1.55.14+: refuse to run while the canvas is select-only
            mutatesGraph: true,  // or () => boolean
        },
    ],
});

Keybindings

keybindings: [
    {
        commandId: "my.ext.doSomething",
        combo: { key: "d", ctrl: true, shift: true },
    },
],

Settings

settings: [
    {
        id: "my.ext.mySetting",
        name: "My Setting",
        type: "boolean",
        defaultValue: true,
        onChange: (value) => { console.log("Setting changed:", value); },
    },
    {
        id: "my.ext.mode",
        name: "Processing Mode",
        type: "combo",
        options: ["fast", "quality", "balanced"],  // or (currentValue) => [...] for dynamic options
        defaultValue: "balanced",
    },
],

onChange(newValue, oldValue) may be async.

Setting types: boolean, number, slider, knob, combo, radio, text, image, color, url, hidden, backgroundImage

Sidebar Tabs

async setup(app) {
    app.extensionManager.registerSidebarTab({
        id: "my-sidebar",
        title: "My Panel",
        icon: "pi pi-cog",
        type: "custom",
        render: (container) => {
            container.innerHTML = "<h3>My Custom Panel</h3>";
        },
        destroy: () => {
            // Cleanup
        },
        // v1.58+: return true to handle the click yourself (skips default open/close)
        onToggle: async () => false,
    });
},

type: "vue" tabs (component: MyVueComponent) must bundle their own Vue UI libraries — the host no longer provides PrimeVue (upcoming; see Breaking Changes).

Bottom Panel Tabs

bottomPanelTabs: [
    {
        id: "my-panel",
        title: "My Panel",
        type: "custom",
        render: (container) => {
            container.innerHTML = "<div>Panel content</div>";
        },
    },
],

Menu Commands

menuCommands: [
    {
        path: ["My Extension"],
        commands: ["my.ext.doSomething"],
    },
],

About Page Badges

aboutPageBadges: [
    { label: "v1.0.0", url: "https://github.com/...", icon: "pi pi-github", severity: "warn" },
    // severity is optional: "danger" | "warn"
],

Top Bar Badges

topbarBadges: [
    {
        text: "My Extension",        // required
        label: "BETA",               // optional badge label
        variant: "info",             // "info" | "warning" | "error"
        icon: "pi pi-star",          // optional icon
        tooltip: "Extension info",   // optional tooltip
    },
],

Action Bar Buttons

actionBarButtons: [
    {
        icon: "pi pi-bolt",           // required
        label: "My Action",           // optional label
        tooltip: "Run my action",     // optional tooltip
        onClick: () => { /* ... */ },  // required click handler
    },
],

API Events

Listen to execution events:

// Node execution completed
app.api.addEventListener("executed", ({ detail }) => {
    const { node, output } = detail;
    // output contains images, text, etc.
});

// Execution progress
app.api.addEventListener("progress", ({ detail }) => {
    const { value, max, node } = detail;
});

// Execution started/completed
app.api.addEventListener("execution_start", ({ detail }) => {});
app.api.addEventListener("execution_success", ({ detail }) => {});
app.api.addEventListener("execution_error", ({ detail }) => {});

// Status updates
app.api.addEventListener("status", ({ detail }) => {
    const { exec_info } = detail;
});

Server-to-Client Communication

Python (server side):

from server import PromptServer

PromptServer.instance.send_sync(
    "my_extension.update",
    {"status": "complete", "data": result}
)

JavaScript (client side):

app.api.addEventListener("my_extension.update", ({ detail }) => {
    console.log("Received:", detail);
});

Calling Your Own Routes

// fetchApi prefixes /api and adds auth headers
const res = await app.api.fetchApi("/my_extension/process", {
    method: "POST",
    body: JSON.stringify(payload),
    timeoutMs: null,  // v1.55.2+: default aborts after 60 s without response headers (TimeoutError)
});

Pass timeoutMs: null (or a larger number) for slow synchronous routes; your own signal is still honored.

Toast Notifications

v1.58+ API — success / info / warning / error / loading(title, options?) return a ToastId:

const toast = app.extensionManager.toast;
const id = toast.loading("Processing…");
// Reusing `id` replaces that toast in place
toast.success("Done", {
    id,
    description: "3 images saved",
    duration: 3000,              // ms; default is no auto-dismiss
    closable: true,
    action: { label: "Open", onClick: () => { /* ... */ } },  // does not auto-dismiss
});
toast.dismiss(id);               // returns true if a toast was removed
toast.dismissAll();

Older frontends only have add(). It still works on v1.58+ but is deprecated; feature-detect:

if (toast.success) toast.success("Saved", { description: "Done", duration: 3000 });
else toast.add({ severity: "success", summary: "Saved", detail: "Done", life: 3000 });
// add() severities: "success" | "info" | "warn" | "error" ("secondary"/"contrast" → info).
// group/styleClass are ignored and remove()/removeAll() are gone on v1.58+.

Dialogs

// Confirmation dialog — resolves true / false, or null if dismissed
const result = await app.extensionManager.dialog.confirm({
    title: "Confirm Action",
    message: "Are you sure?",
    type: "delete",            // optional: "default" | "overwrite" | "delete" | "info" | ...
    itemList: ["a.png"],       // optional bullet list under the message
    hint: "Cannot be undone",  // optional
    key: "my-ext-confirm",     // v1.53+: own dialog key so an already-open shared prompt can't swallow it
});

// Prompt dialog
const value = await app.extensionManager.dialog.prompt({
    title: "Enter Value",
    message: "Provide a name:",
    defaultValue: "default",
});

ExtensionManager Utilities

Setting Access

// Read a setting value
const val = app.extensionManager.setting.get("my.ext.mySetting");

// Write a setting value
app.extensionManager.setting.set("my.ext.mySetting", newValue);

Execution Errors (read-only)

// Last node-level errors (keyed by node ID)
const nodeErrors = app.extensionManager.lastNodeErrors;

// Last execution-level error
const execError = app.extensionManager.lastExecutionError;

Markdown Rendering

// Render markdown to sanitized HTML (marked + DOMPurify, safe for innerHTML)
const html = app.extensionManager.renderMarkdownToHtml(markdownStr, baseUrl);

Context Menu Items

app.registerExtension({
    name: "my.ext",

    // Canvas right-click menu
    getCanvasMenuItems(canvas) {
        return [{
            content: "My Action",
            callback: () => { console.log("Canvas menu clicked"); },
        }];
    },

    // Node right-click menu
    getNodeMenuItems(node) {
        if (node.comfyClass === "MyNode") {
            return [{
                content: "Custom Action",
                callback: () => { console.log("Node:", node.id); },
            }];
        }
        return [];
    },
});

Node Instance Properties (LGraphNode Augmentations)

// Available on node instances:
node.comfyClass       // ComfyUI node type name
node.isVirtualNode    // true for frontend-only nodes
node.imgs             // preview images array
node.imageIndex       // current preview image index

// Callbacks:
node.onExecuted = function(output) { /* execution result */ };
node.onExecutionStart = function() { /* about to execute */ };
node.onDragOver = function(event) { /* file drag over */ };
node.onDragDrop = function(event) { /* file dropped */ };

Recent Breaking Changes (frontend 1.4x – 1.58, plus upcoming)

Changes extension authors should be aware of. Upstream migration notes with details: https://github.com/Comfy-Org/ComfyUI_frontend/tree/main/docs/extensions (widgets-migration.md, connection-callbacks-migration.md, serialization-callbacks-migration.md, node-geometry-migration.md, link-registration-migration.md, primevue-removal-migration.md, tooltip-migration.md).

  • PrimeVue removed (upcoming, after v1.58) — no $primevue, no PrimeVue theme, no global --p-* CSS variables. Use design tokens instead: --primary-background, --base-foreground, --muted-foreground, --base-background, --secondary-background, --border-default. To keep using PrimeVue components, mount your own Vue app with PrimeVue installed. pi pi-* icon classes still work.
  • PrimeVue tooltip gone (v1.58+) — no v-tooltip / .p-tooltip. An open tooltip is [data-slot="tooltip-content"] on document.body.
  • Toast API replaced (v1.58+) — see Toast Notifications. add() / addAlert() are deprecated; remove() / removeAll() are removed.
  • Widget values are store-backed (v1.53+) — see Widget Rules (unique names, removeWidget, node.widgets ??= []).
  • input.link / output.links deprecated (v1.53+) — reads still work but warn and may lag the graph. Writes no longer change links, except that input.link = null disconnects. Use node.isInputConnected(i), node.getInputLink(i), node.isOutputConnected(i), node.getOutputNodes(i), node.connect(), node.disconnectInput(i). The node:slot-links:changed and node:slot-errors:changed graph events are removed. For add/remove notifications with several subscribers, use graph.events.addEventListener("node:added" | "node:before-removed" | "node:removed", ...).
  • onConfigure(data) receives a shallow copy (v1.55.2+) — changing top-level keys of data has no effect. Persist custom state in node.properties / graph.extra.
  • Core node fields are accessors (v1.53+) — id, type, title, mode, flags, color, bgcolor, shape no longer appear in Object.keys(node) / {...node}; use node.serialize(). Changing node.type after construction warns.
  • node.size is the requested size — getBounding() / boundingRect give the rendered footprint (can be larger). canvas.repositionNodesVueMode() → canvas.applyNodePositions() (old name kept as deprecated alias).
  • canvas.selected_nodes deprecated (upcoming) — warns and returns a snapshot. Read canvas.selectedItems (a snapshot Set; re-read it after add/delete) and change the selection with canvas.selectItems(items, addToCurrent?).
  • Minor deprecations — node.badgePosition (badges always render top-right; assignment is ignored), node.widgets_up (use widgets_start_y), options.canvasOnly (use options.surfaces).
  • Group nodes removed — group nodes can no longer be created; workflows containing them auto-convert to subgraphs on load. GroupNodeHandler / GroupNodeConfig remain re-exported for backward compatibility only. Use subgraphs for new work.
  • LiteGraph.use_uuids removed — node IDs are always numeric. Don't read or set this flag (UUIDs are still used internally for subgraph/slot IDs).
  • LGraph.onGetNodeMenuOptions removed; LGraph.onBeforeChange deprecated — assigning it still works but warns; use LGraphCanvas.onBeforeChange instead.
  • IBaseWidget.entityId removed — widget identity is the widgetId branded key (graphId:nodeId:name); promoted subgraph widgets are store-backed.
  • node.size is Proxy-backed — both node.size[1] = h and node.size = [w, h] now correctly reflow Vue-rendered nodes; no polling workarounds needed.

Frontend Scripts API

Custom node JavaScript can import from the frontend's src/scripts/ modules. Imports use the Vite shim pattern:

import { app } from "../../scripts/app.js";
import { api } from "../../scripts/api.js";

Symbols are also accessible via window.comfyAPI.<module>.<export>. Only directly declared exports (export const|let|var|function|class) are shimmed; re-exports such as export { x } from "..." are not reachable this way.

Stability Levels

LevelModulesNotes
Stablescripts/app, scripts/apiGuaranteed public API
Internal (console warning)scripts/widgets, scripts/domWidget, scripts/utils, scripts/pnginfo, scripts/changeTracker, scripts/defaultGraph, scripts/metadata/*Usable but may change
Deprecatedscripts/uiWill be removed; use Vue alternatives

Key Modules

  • scripts/api — ComfyApi class: fetchApi(), queuePrompt(), getNodeDefs(), WebSocket events, settings, user data, system stats
  • scripts/app — ComfyApp singleton (app): graph operations, registerExtension(), extensionManager, clipboard, coordinate conversion
  • scripts/widgets — ComfyWidgets registry (INT, FLOAT, STRING, BOOLEAN, COMBO, IMAGEUPLOAD, etc.), addValueControlWidget(s)(), updateControlWidgetLabel() (IS_CONTROL_WIDGET no longer exported since v1.58)
  • scripts/domWidget — addDOMWidget(), DOMWidgetImpl, ComponentWidgetImpl (Vue component wrapper)
  • scripts/utils — clone(), addStylesheet(), uploadFile(), storage helpers
  • scripts/pnginfo — getPngMetadata(), getWebpMetadata(), importA1111(), format-specific extractors

For full API details, see the API Reference.

See Also

  • comfyui-node-basics - Backend node structure
  • comfyui-node-packaging - Project structure with JS extensions
  • comfyui-node-inputs - Backend input types

ComfyUI Node Inputs

Inputs define what data a node accepts. Widget inputs create UI controls; connection inputs create socket slots.

Widget Input Types

INT

io.Int.Input("seed",
    default=0,
    min=0,
    max=0xffffffffffffffff,
    step=1,
    control_after_generate=True,  # adds increment/decrement/randomize control
    display_mode=io.NumberDisplay.number,  # "number", "slider", or "gradient_slider"
    tooltip="Random seed for generation",
)

NumberDisplay options: io.NumberDisplay.number, io.NumberDisplay.slider, io.NumberDisplay.gradient_slider

ControlAfterGenerate options: True (default randomize), or io.ControlAfterGenerate.fixed, .increment, .decrement, .randomize. A mode value is treated as the control's starting mode only from frontend v1.57.0 (#19867); older frontends used the string as the control widget's name.

FLOAT

io.Float.Input("strength",
    default=1.0,
    min=0.0,
    max=10.0,
    step=0.01,
    round=0.001,         # rounding precision
    display_mode=io.NumberDisplay.slider,
    gradient_stops=[{"offset": 0.0, "color": [0, 0, 0]}, {"offset": 1.0, "color": [255, 255, 255]}],  # for gradient_slider mode
    tooltip="Effect strength",
)

STRING

# Single-line string
io.String.Input("name",
    default="",
    placeholder="Enter name...",
)

# Multi-line text area
io.String.Input("prompt",
    multiline=True,
    default="",
    placeholder="Enter prompt...",
    dynamic_prompts=True,  # enable dynamic prompt syntax
)

BOOLEAN

io.Boolean.Input("enabled",
    default=True,
    label_on="Enabled",
    label_off="Disabled",
    tooltip="Toggle this feature",
)

COMBO (Dropdown)

io.Combo.Input("mode",
    options=["option_a", "option_b", "option_c"],
    default="option_a",
    tooltip="Select processing mode",
    control_after_generate=True,  # adds increment/decrement/randomize control
)

Combo with Enum:

from enum import Enum

class BlendMode(Enum):
    NORMAL = "normal"
    MULTIPLY = "multiply"
    SCREEN = "screen"

io.Combo.Input("blend", options=BlendMode, default=BlendMode.NORMAL)
# Enum values auto-converted to string list

Combo with file upload:

io.Combo.Input("image_file",
    options=[],
    upload=io.UploadType.image,          # .image, .audio, .video, .model (for generic file upload)
    image_folder=io.FolderType.input,    # .input, .output, .temp
)

Dynamic combo with remote options:

io.Combo.Input("model_name",
    options=[],
    remote=io.RemoteOptions(
        route="/internal/models/checkpoints",
        refresh_button=True,
        control_after_refresh="first",  # "first" or "last"
        timeout=5000,        # ms
        max_retries=3,
        refresh=60000,       # TTL refresh interval in ms
    ),
)

Security: treat combo / DynamicCombo values as untrusted when they reach the filesystem. Re-validate any value used as a file/folder name, path, format or extension at the load/save boundary (folder_paths.get_full_path_or_raise(...), folder_paths.is_within_directory(base, path), or a fixed allowlist) — prompts can be submitted via the API with values outside options.

MULTICOMBO (Multi-select Dropdown)

io.MultiCombo.Input("tags",
    options=["tag1", "tag2", "tag3", "tag4"],
    default=["tag1"],
    placeholder="Select tags...",
    chip=True,  # display as chips
)
# Value type: list[str]

COLOR (Color Picker)

io.Color.Input("color",
    default="#ffffff",
    socketless=True,  # widget only by default
)
# Value type: str (hex color)

COLORS (Color Palette)

io.Colors.Input("palette",
    default=["#ff0000", "#00ff00"],
    socketless=True,
)
# Value type: list[str] (hex colors)

BOUNDING_BOX (Rectangle Selector)

io.BoundingBox.Input("region",
    default={"x": 0, "y": 0, "width": 512, "height": 512},
    socketless=True,
    component="my_component",  # optional custom UI component name
    force_input=False,
)
# Value type: {"x": int, "y": int, "width": int, "height": int}

BOUNDING_BOXES (Multiple Regions)

io.BoundingBoxes.Input("regions",
    default=[],
    socketless=True,
)
# Value type: list of {"x": int, "y": int, "width": int, "height": int, "metadata": dict}

CURVE (Spline Editor)

io.Curve.Input("curve",
    default=[(0.0, 0.0), (1.0, 1.0)],  # linear ramp
    socketless=True,
)
# Value type: raw curve data; normalize with CurveInput.from_raw(value)
# (from comfy_api.input import CurveInput)

RANGE (Levels/Range Editor)

io.Range.Input("levels",
    default={"min": 0.0, "max": 1.0},
    gradient_stops=None,     # gradient background for the slider
    show_midpoint=True,      # gamma midpoint handle
    value_min=0.0,
    value_max=1.0,
)
# Value type: raw dict; normalize with RangeInput.from_raw(value)
# (from comfy_api.input import RangeInput) -> .min_val, .max_val, .midpoint, .to_lut()

WEBCAM (Camera Capture)

io.Webcam.Input("capture")
# Value type: str

IMAGECOMPARE (Comparison Widget)

io.ImageCompare.Input("comparison", socketless=True)
# Value type: dict

Newer editor widgets (v0.31–v0.40, need a matching frontend)

io.VideoEdit.Input("trim", features=["trim"])   # "trim" and/or "crop" (default both)
# Value: {"trim": {"start_time": float, "duration": float}, "crop": {"x","y","width","height"}}
#   apply with video.as_trimmed(...) / video.as_cropped(...); zero width/height = full frame
io.ResolutionPreview.Input("preview",            # live preview of a computed size; optional by default
    ratio_widget="aspect_ratio", megapixels_widget="megapixels", multiple_widget="multiple")
io.Compositor.Input("compositor")                # layer-editor state dict (pairs with io.Layers)
io.CameraInfoState.Input("camera_info_state", optional=True)  # camera editor state dict

Input Options (Common to All)

io.Image.Input("image",
    optional=True,        # not required; creates optional input socket
    tooltip="Description shown on hover",
    lazy=True,            # lazy evaluation - only computed when needed
    advanced=True,        # hidden by default in compact mode
    raw_link=True,        # receive raw link reference instead of value
)

force_input

Forces a widget input to appear as a connection socket instead of a widget:

io.Float.Input("value",
    default=1.0,
    force_input=True,   # shows as socket, not slider
)

socketless

Makes a widget input appear only as a widget with no input socket:

io.String.Input("note",
    default="",
    socketless=True,     # widget only, no connection socket
)

Optional Inputs

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode",
            display_name="My Node",
            category="example",
            inputs=[
                io.Image.Input("image"),                        # required
                io.Mask.Input("mask", optional=True),           # optional
                io.Float.Input("blend", default=0.5),           # has default widget
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def execute(cls, image, mask=None, blend=0.5):
        # Optional inputs default to None when not connected
        if mask is not None:
            image = image * (1 - blend) + image * mask.unsqueeze(-1) * blend
        return io.NodeOutput(image)

Hidden Inputs

Hidden inputs receive server-provided values, not user input:

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode",
            display_name="My Node",
            category="example",
            inputs=[io.String.Input("text")],
            outputs=[io.String.Output()],
            hidden=[
                io.Hidden.unique_id,       # node's unique ID
                io.Hidden.prompt,           # full prompt data
                io.Hidden.extra_pnginfo,    # PNG metadata dict
                io.Hidden.dynprompt,        # dynamic prompt object
                io.Hidden.auth_token_comfy_org,  # auth token
                io.Hidden.api_key_comfy_org,     # API key
                io.Hidden.comfy_usage_source,    # prompt source, e.g. "comfyui-frontend"
                # io.Hidden.execution_list exists (v0.36+) but is core-internal and
                # slated for removal - DO NOT USE
            ],
        )

    @classmethod
    def execute(cls, text):
        # Access hidden values via cls.hidden
        node_id = cls.hidden.unique_id
        prompt = cls.hidden.prompt
        extra = cls.hidden.extra_pnginfo
        return io.NodeOutput(f"{text} (node: {node_id})")

Lazy Evaluation

Lazy inputs are only evaluated when actually needed, saving computation:

class ConditionalNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ConditionalNode",
            display_name="Conditional",
            category="logic",
            inputs=[
                io.Boolean.Input("condition"),
                io.Image.Input("if_true", lazy=True),
                io.Image.Input("if_false", lazy=True),
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def check_lazy_status(cls, condition, if_true=None, if_false=None):
        """Return list of input names that need evaluation."""
        if condition and if_true is None:
            return ["if_true"]
        if not condition and if_false is None:
            return ["if_false"]
        return []

    @classmethod
    def execute(cls, condition, if_true, if_false):
        return io.NodeOutput(if_true if condition else if_false)

Rules for lazy evaluation:

  • Mark inputs with lazy=True
  • Implement check_lazy_status() classmethod
  • Unevaluated inputs are None; a disconnected optional lazy input is absent from kwargs — use a sentinel default (MISSING = object()) to distinguish (see the Switch pattern in comfyui-node-advanced)
  • Return list of input names that need computing, or empty list
  • Method may be called multiple times
  • Lazy sub-inputs of Autogrow/DynamicCombo arrive as (value, key) tuples here (see comfyui-node-advanced)

Input tolerance (core policy): don't reject values just because they exceed recommended/UI limits or may give poor results; adapt (clamp/pad/resize) only when the operation would otherwise fail. Security checks (path containment) still apply.

V1 Input Format (Legacy Reference)

@classmethod
def INPUT_TYPES(s):
    return {
        "required": {
            "image": ("IMAGE",),
            "strength": ("FLOAT", {
                "default": 1.0, "min": 0.0, "max": 10.0, "step": 0.01
            }),
            "mode": (["option_a", "option_b"],),
            "text": ("STRING", {"multiline": True, "default": ""}),
        },
        "optional": {
            "mask": ("MASK",),
        },
        "hidden": {
            "unique_id": "UNIQUE_ID",
            "prompt": "PROMPT",
            "extra_pnginfo": "EXTRA_PNGINFO",
        },
    }

Complete Example: Multi-Input Node

class AdvancedImageNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="AdvancedImageNode",
            display_name="Advanced Image",
            category="image/advanced",
            description="Demonstrates various input types",
            inputs=[
                # Required connection input
                io.Image.Input("image", tooltip="Input image"),
                # Required widget inputs
                io.Float.Input("brightness", default=1.0, min=0.0, max=3.0,
                               step=0.1, display_mode=io.NumberDisplay.slider),
                io.Float.Input("contrast", default=1.0, min=0.0, max=3.0, step=0.1),
                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff,
                             control_after_generate=True),
                io.Combo.Input("blend_mode", options=["normal", "multiply", "screen"]),
                io.Boolean.Input("flip_horizontal", default=False),
                io.String.Input("label", default="", socketless=True),
                # Optional inputs
                io.Mask.Input("mask", optional=True),
                io.Image.Input("overlay", optional=True),
                # Advanced inputs (collapsed by default)
                io.Float.Input("gamma", default=1.0, min=0.1, max=3.0, advanced=True),
            ],
            outputs=[
                io.Image.Output("IMAGE"),
                io.Mask.Output("MASK"),
            ],
        )

    @classmethod
    def execute(cls, image, brightness, contrast, seed, blend_mode,
                flip_horizontal, label, mask=None, overlay=None, gamma=1.0):
        result = image * brightness
        if flip_horizontal:
            result = torch.flip(result, dims=[2])
        if mask is not None:
            result = result * mask.unsqueeze(-1)
        return io.NodeOutput(result, mask if mask is not None else torch.ones(result.shape[:3]))

See Also

  • comfyui-node-basics - Node structure overview
  • comfyui-node-datatypes - Data type details
  • comfyui-node-advanced - MatchType, Autogrow, DynamicCombo
  • comfyui-node-lifecycle - Lazy evaluation details

ComfyUI Node Execution Lifecycle

Understanding the execution lifecycle helps build efficient, correct nodes.

Execution Flow Overview

1. Prompt received from frontend
2. Validation phase
   ├── Look up each node class
   ├── Call INPUT_TYPES() / define_schema() for input specs
   ├── Validate connections and types
   ├── Call validate_inputs() for each node
   └── Validate loop boundaries (StartLoop/EndLoop pairing, v0.36+)
3. Build execution order (topological sort from output nodes)
4. For each node in order:
   ├── Cache check (fingerprint_inputs)
   ├── Input resolution (get upstream values)
   ├── Lazy evaluation (check_lazy_status)
   ├── Execute function
   └── Store outputs in cache
5. Return results to frontend

Execution Order

ComfyUI executes from output nodes backward:

  1. Identifies output nodes (is_output_node=True)
  2. Builds dependency graph
  3. Topological sort determines execution order
  4. Only nodes connected to output nodes execute

Cache Control: fingerprint_inputs (V3) / IS_CHANGED (V1)

Controls when a node re-executes vs uses cached results.

class RandomNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="RandomNode",
            display_name="Random Value",
            category="utils",
            inputs=[
                io.Float.Input("min_val", default=0.0),
                io.Float.Input("max_val", default=1.0),
            ],
            outputs=[io.Float.Output("FLOAT")],
        )

    @classmethod
    def fingerprint_inputs(cls, min_val, max_val):
        """Return value compared to last run. Different value = re-execute."""
        # Return unique value each time to always re-execute
        import time
        return time.time()

    @classmethod
    def execute(cls, min_val, max_val):
        import random
        return io.NodeOutput(random.uniform(min_val, max_val))

How caching works:

  • Before execution, fingerprint_inputs() is called with the same args as execute()
  • Return value is compared to the previous run's return value
  • If same → skip execution, use cached output
  • If different → re-execute the node
  • If fingerprint_inputs is not defined → cache based on input values

V1 equivalent (IS_CHANGED):

@classmethod
def IS_CHANGED(s, min_val, max_val):
    return time.time()  # always re-execute

not_idempotent Flag

For nodes that should never be cached:

io.Schema(
    node_id="AlwaysRunNode",
    not_idempotent=True,  # prevents cache sharing between instances of the same node
    # ...
)

Important: not_idempotent=True does not prevent a node from reusing its own cached output on subsequent runs. It only prevents cache sharing between different instances of the same node type that have identical inputs. To force re-execution every run (e.g., for file-writing nodes), you must also implement fingerprint_inputs (V3) or IS_CHANGED (V1) returning a unique value each time.

has_intermediate_output Flag

For nodes with interactive UI that produce intermediate outputs (e.g., Image Crop, Painter). These behave like output nodes (UI results are cached and resent to the frontend on page refresh) but do NOT automatically get added to the execution list — they only execute if on the dependency path of a real output node.

io.Schema(
    node_id="InteractiveCropNode",
    has_intermediate_output=True,
    # ...
)

External Cache Providers

Share cached node outputs across ComfyUI instances (e.g. a shared network cache) by registering a CacheProvider:

from comfy_api.latest import Caching

class MyCacheProvider(Caching.CacheProvider):
    async def on_lookup(self, context):   # context: node_id, class_type, cache_key_hash
        ...  # return Caching.CacheValue(outputs=[...], ui={...}) or None on miss

    async def on_store(self, context, value):
        ...  # store to external storage (dispatched as a background task)

    def should_cache(self, context, value=None) -> bool:
        return True  # return False to skip external caching for a node

    def on_prompt_start(self, prompt_id): ...
    def on_prompt_end(self, prompt_id): ...

# Register in ComfyExtension.on_load():
api = ComfyAPI()
await api.caching.register_provider(MyCacheProvider())

Providers are consulted on local cache miss, in registration order. Exceptions from providers never break execution.

On a cache hit the cached UI is resent (with id/preview_id stripped from UI entries — see comfyui-node-outputs). For RAM-cache sizing of custom output objects see _comfy_cache_tensors in comfyui-node-datatypes.

Input Validation: validate_inputs (V3) / VALIDATE_INPUTS (V1)

Validates inputs before execution. Runs during the validation phase.

class ValidatedNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ValidatedNode",
            display_name="Validated Node",
            category="utils",
            inputs=[
                io.Int.Input("width", default=512, min=1, max=8192),
                io.Int.Input("height", default=512, min=1, max=8192),
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def validate_inputs(cls, width, height):
        """Return True if valid, or error string if invalid."""
        if width % 8 != 0 or height % 8 != 0:
            return "Width and height must be multiples of 8"
        if width * height > 4096 * 4096:
            return "Total pixels exceed maximum (4096x4096)"
        return True

    @classmethod
    def execute(cls, width, height):
        import torch
        return io.NodeOutput(torch.zeros(1, height, width, 3))

V1 equivalent:

@classmethod
def VALIDATE_INPUTS(s, width, height):
    if width % 8 != 0:
        return "Width must be a multiple of 8"
    return True

Dynamic Inputs in validate_inputs (v0.40+)

Name the root id of an Autogrow / DynamicCombo input to receive its rebuilt nested value; dynamic roots you don't name are not passed. **kwargs receives everything, nested.

@classmethod
def validate_inputs(cls, rows):          # rows = {"item0": 0.5, ...} (Autogrow)
    return True if rows else "Connect at least one row"
  • Returning False/a string is reported even when no inputs were passed.
  • Malformed dynamic keys fail validation with error type invalid_dynamic_input.

Skipping Type Validation

To accept any type (wildcard inputs), include input_types parameter:

@classmethod
def validate_inputs(cls, input_types: dict = None, **kwargs):
    # input_types contains the actual types of connected inputs
    # Returning True skips the default type checking
    return True

Lazy Evaluation: check_lazy_status

Controls which lazy inputs actually need evaluation. See comfyui-node-inputs for full details.

@classmethod
def check_lazy_status(cls, condition, value_a=None, value_b=None):
    """Called before execute. Return names of inputs that need evaluation."""
    if condition and value_a is None:
        return ["value_a"]
    if not condition and value_b is None:
        return ["value_b"]
    return []

Key behaviors:

  • Only called if the node has lazy inputs
  • May be called multiple times as inputs become available
  • Unevaluated lazy inputs are None
  • Return empty list (or None) when ready to execute
  • Evaluated inputs retain their value across calls

Output Nodes

Nodes with is_output_node=True are execution roots — ComfyUI traces backward from these:

class SaveMyData(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="SaveMyData",
            display_name="Save Data",
            category="output",
            is_output_node=True,  # marks as output node
            inputs=[
                io.String.Input("data"),
                io.String.Input("filename", default="output.txt"),
            ],
            outputs=[],  # output nodes may have no outputs
            hidden=[io.Hidden.prompt, io.Hidden.extra_pnginfo],
        )

    @classmethod
    def execute(cls, data, filename):
        import folder_paths, os
        output_dir = folder_paths.get_output_directory()
        with open(os.path.join(output_dir, filename), 'w') as f:
            f.write(data)
        return io.NodeOutput()

List Processing

Receiving Lists

# V3: is_input_list=True in Schema (same as V1 INPUT_IS_LIST)
# All inputs arrive as lists — including widget values like batch_size
# Widget values: use widget_value[0] to get the scalar
# Shorter lists are padded by repeating the last value

# V1: INPUT_IS_LIST = True to receive full lists
class ListNode:
    INPUT_IS_LIST = True
    # Now execute() receives lists instead of individual items

Outputting Lists

# V3
io.Image.Output("IMAGE", is_output_list=True)

# V1
OUTPUT_IS_LIST = (True,)  # tuple matching RETURN_TYPES

Error Handling

@classmethod
def execute(cls, image, model):
    try:
        result = model.process(image)
    except RuntimeError as e:
        if "out of memory" in str(e):
            import torch
            torch.cuda.empty_cache()
            # Try with smaller batch
            result = process_in_chunks(image, model)
        else:
            raise
    return io.NodeOutput(result)

Server Communication

Send messages to the frontend during execution:

from server import PromptServer

@classmethod
def execute(cls, data):
    PromptServer.instance.send_sync(
        "my_extension.status",
        {"message": "Processing complete", "progress": 100}
    )
    # Status text shown on the node (binary TEXT event; sid=None broadcasts)
    PromptServer.instance.send_progress_text("Step 3 / 10", cls.hidden.unique_id)
    return io.NodeOutput(data)
  • Dict payloads that contain "prompt_id" get the prompt's workflow_metadata (e.g. workflow_id) merged in (v0.40+) — include prompt_id so clients can route the message to its workflow.

Logging

Use logging. For verbose diagnostics below INFO use the DETAIL level (v0.30+): from comfy.internal_logging import detail; detail("msg %s", x), shown with --verbose DETAIL or written with --verbose DETAIL path.log. (The module is comfy.internal_logging, not comfy.logging.)

Complete Lifecycle Example

import time
import torch
from comfy_api.latest import ComfyExtension, io, ComfyAPISync

class FullLifecycleNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="FullLifecycleNode",
            display_name="Full Lifecycle Demo",
            category="example",
            inputs=[
                io.Image.Input("image"),
                io.Float.Input("threshold", default=0.5, min=0.0, max=1.0),
                io.Image.Input("optional_ref", optional=True, lazy=True),
            ],
            outputs=[
                io.Image.Output("IMAGE"),
                io.Mask.Output("MASK"),
            ],
            hidden=[io.Hidden.unique_id],
        )

    @classmethod
    def validate_inputs(cls, image, threshold, optional_ref=None):
        if threshold == 0.0:
            return "Threshold cannot be exactly 0"
        return True

    @classmethod
    def fingerprint_inputs(cls, image, threshold, optional_ref=None):
        # Re-execute if threshold changed; cache otherwise
        return threshold

    @classmethod
    def check_lazy_status(cls, image, threshold, optional_ref=None):
        # Only request optional_ref if threshold is high
        if threshold > 0.8 and optional_ref is None:
            return ["optional_ref"]
        return []

    @classmethod
    def execute(cls, image, threshold, optional_ref=None):
        node_id = cls.hidden.unique_id

        api = ComfyAPISync()  # use ComfyAPISync in sync execute; ComfyAPI in async
        api.execution.set_progress(0, 2)

        # Generate mask from threshold
        gray = image[:, :, :, 0] * 0.299 + image[:, :, :, 1] * 0.587 + image[:, :, :, 2] * 0.114
        mask = (gray > threshold).float()

        api.execution.set_progress(1, 2)

        # Apply mask
        result = image * mask.unsqueeze(-1)
        if optional_ref is not None:
            result = result + optional_ref * (1 - mask.unsqueeze(-1))

        api.execution.set_progress(2, 2)
        return io.NodeOutput(result, mask)

See Also

  • comfyui-node-basics - Node structure fundamentals
  • comfyui-node-inputs - Input types and lazy evaluation
  • comfyui-node-advanced - Expansion, MatchType, DynamicCombo
  • comfyui-node-outputs - UI outputs and previews

ComfyUI V1 → V3 Migration Guide

Migrate existing V1 nodes to the modern V3 API. V3 uses classmethods, typed inputs/outputs, and ComfyExtension registration.

Migration Checklist

  1. Change base class to io.ComfyNode
  2. Replace INPUT_TYPES() with define_schema() returning io.Schema
  3. Rename execution function to execute and make it a @classmethod
  4. Replace return tuples with io.NodeOutput(...)
  5. Replace IS_CHANGED with fingerprint_inputs
  6. Replace VALIDATE_INPUTS with validate_inputs
  7. Convert check_lazy_status to @classmethod
  8. Replace NODE_CLASS_MAPPINGS with ComfyExtension + comfy_entrypoint()
  9. Access hidden inputs via cls.hidden instead of kwargs
  10. Remove __init__ methods (no instance state in V3)

Side-by-Side Comparison

V1 (Before)

import torch

class ImageInvertV1:
    CATEGORY = "image"
    FUNCTION = "invert"
    RETURN_TYPES = ("IMAGE",)
    RETURN_NAMES = ("image",)
    OUTPUT_TOOLTIPS = ("The inverted image",)
    DESCRIPTION = "Inverts image colors"

    @classmethod
    def INPUT_TYPES(s):
        return {
            "required": {
                "image": ("IMAGE",),
                "strength": ("FLOAT", {
                    "default": 1.0,
                    "min": 0.0,
                    "max": 1.0,
                    "step": 0.01,
                }),
            },
            "optional": {
                "mask": ("MASK",),
            },
            "hidden": {
                "unique_id": "UNIQUE_ID",
            },
        }

    @classmethod
    def IS_CHANGED(s, image, strength, mask=None, unique_id=None):
        return strength

    @classmethod
    def VALIDATE_INPUTS(s, image, strength, mask=None, unique_id=None):
        if strength < 0:
            return "Strength must be non-negative"
        return True

    def invert(self, image, strength, mask=None, unique_id=None):
        inverted = 1.0 - image
        result = image * (1 - strength) + inverted * strength
        if mask is not None:
            result = image * (1 - mask.unsqueeze(-1)) + result * mask.unsqueeze(-1)
        return (result,)

NODE_CLASS_MAPPINGS = {"ImageInvertV1": ImageInvertV1}
NODE_DISPLAY_NAME_MAPPINGS = {"ImageInvertV1": "Invert Image"}

V3 (After)

import torch
from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

class ImageInvertV3(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ImageInvertV3",
            display_name="Invert Image",
            description="Inverts image colors",
            category="image",
            inputs=[
                io.Image.Input("image"),
                io.Float.Input("strength", default=1.0, min=0.0, max=1.0, step=0.01),
                io.Mask.Input("mask", optional=True),
            ],
            outputs=[
                io.Image.Output("IMAGE", tooltip="The inverted image"),
            ],
            hidden=[io.Hidden.unique_id],
        )

    @classmethod
    def fingerprint_inputs(cls, image, strength, mask=None):
        return strength

    @classmethod
    def validate_inputs(cls, image, strength, mask=None):
        if strength < 0:
            return "Strength must be non-negative"
        return True

    @classmethod
    def execute(cls, image, strength, mask=None):
        node_id = cls.hidden.unique_id  # access hidden via cls.hidden

        inverted = 1.0 - image
        result = image * (1 - strength) + inverted * strength
        if mask is not None:
            result = image * (1 - mask.unsqueeze(-1)) + result * mask.unsqueeze(-1)
        return io.NodeOutput(result)


class MyExtension(ComfyExtension):
    @override
    async def get_node_list(self) -> list[type[io.ComfyNode]]:
        return [ImageInvertV3]

async def comfy_entrypoint() -> MyExtension:
    return MyExtension()

Property Mapping

V1 PropertyV3 Equivalent
CATEGORY = "image"io.Schema(category="image")
FUNCTION = "my_func"Always execute (fixed name)
RETURN_TYPES = ("IMAGE",)outputs=[io.Image.Output()]
RETURN_NAMES = ("image",)outputs=[io.Image.Output(display_name="image")]
OUTPUT_TOOLTIPS = ("tip",)outputs=[io.Image.Output(tooltip="tip")]
OUTPUT_NODE = Trueio.Schema(is_output_node=True)
DEPRECATED = Trueio.Schema(is_deprecated=True)
EXPERIMENTAL = Trueio.Schema(is_experimental=True)
API_NODE = Trueio.Schema(is_api_node=True)
NOT_IDEMPOTENT = Trueio.Schema(not_idempotent=True)
DESCRIPTION = "..."io.Schema(description="...")
SEARCH_ALIASES = [...]io.Schema(search_aliases=[...])
INPUT_IS_LIST = Trueio.Schema(is_input_list=True)
OUTPUT_IS_LIST = (True,)io.Image.Output(is_output_list=True)
DEV_ONLY = Trueio.Schema(is_dev_only=True)
ESSENTIALS_CATEGORY = "Basic"io.Schema(essentials_category="Basic")

Input Type Mapping

V1 InputV3 Input
("IMAGE",)io.Image.Input("id")
("MASK",)io.Mask.Input("id")
("LATENT",)io.Latent.Input("id")
("MODEL",)io.Model.Input("id")
("CLIP",)io.Clip.Input("id")
("VAE",)io.Vae.Input("id")
("CONDITIONING",)io.Conditioning.Input("id")
("INT", {"default": 0, ...})io.Int.Input("id", default=0, ...)
("FLOAT", {"default": 1.0, ...})io.Float.Input("id", default=1.0, ...)
("STRING", {"multiline": True})io.String.Input("id", multiline=True)
("BOOLEAN", {"default": True})io.Boolean.Input("id", default=True)
(["opt1", "opt2"],)io.Combo.Input("id", options=["opt1", "opt2"])
("CONTROL_NET",)io.ControlNet.Input("id")
("CLIP_VISION",)io.ClipVision.Input("id")
("CLIP_VISION_OUTPUT",)io.ClipVisionOutput.Input("id")
("STYLE_MODEL",)io.StyleModel.Input("id")
("GLIGEN",)io.Gligen.Input("id")
("UPSCALE_MODEL",)io.UpscaleModel.Input("id")
("AUDIO",)io.Audio.Input("id")
("VIDEO",)io.Video.Input("id")
("SAMPLER",)io.Sampler.Input("id")
("SIGMAS",)io.Sigmas.Input("id")
("NOISE",)io.Noise.Input("id")
("GUIDER",)io.Guider.Input("id")
("HOOKS",)io.Hooks.Input("id")
("LORA_MODEL",)io.LoraModel.Input("id")
("MESH",)io.Mesh.Input("id")
("VOXEL",)io.Voxel.Input("id")
("FILE_3D",)io.File3DAny.Input("id")
("FILE_3D_GLB",)io.File3DGLB.Input("id")
("SVG",)io.SVG.Input("id")
("COLOR",)io.Color.Input("id")
("BOUNDING_BOX",)io.BoundingBox.Input("id")
("CURVE",)io.Curve.Input("id")
("LATENT_UPSCALE_MODEL",)io.LatentUpscaleModel.Input("id")
("MODEL_PATCH",)io.ModelPatch.Input("id")
("HOOK_KEYFRAMES",)io.HookKeyframes.Input("id")
("AUDIO_ENCODER",)io.AudioEncoder.Input("id")
("AUDIO_ENCODER_OUTPUT",)io.AudioEncoderOutput.Input("id")
("TRACKS",)io.Tracks.Input("id")
("LOSS_MAP",)io.LossMap.Input("id")
("TIMESTEPS_RANGE",)io.TimestepsRange.Input("id")
("LATENT_OPERATION",)io.LatentOperation.Input("id")
("WEBCAM",)io.Webcam.Input("id")
("PHOTOMAKER",)io.Photomaker.Input("id")
("WAN_CAMERA_EMBEDDING",)io.WanCameraEmbedding.Input("id")
("LOAD_3D",)io.Load3D.Input("id")
("LOAD_3D_ANIMATION",)io.Load3DAnimation.Input("id")
("LOAD3D_CAMERA",)io.Load3DCamera.Input("id")
("FILE_3D_GLTF",)io.File3DGLTF.Input("id")
("FILE_3D_FBX",)io.File3DFBX.Input("id")
("FILE_3D_OBJ",)io.File3DOBJ.Input("id")
("FILE_3D_STL",)io.File3DSTL.Input("id")
("FILE_3D_USDZ",)io.File3DUSDZ.Input("id")
("FILE_3D_PLY",)io.File3DPLY.Input("id")
("FILE_3D_SPLAT",)io.File3DSPLAT.Input("id")
("FILE_3D_SPZ",)io.File3DSPZ.Input("id")
("FILE_3D_KSPLAT",)io.File3DKSPLAT.Input("id")
("FILE_3D_SPLAT_ANY",)io.File3DSplatAny.Input("id")
("FILE_3D_POINT_CLOUD_ANY",)io.File3DPointCloudAny.Input("id")
("SPLAT",)io.Splat.Input("id")
("LOAD3D_MODEL_INFO",)io.Load3DModelInfo.Input("id")
("BACKGROUND_REMOVAL",)io.BackgroundRemoval.Input("id")
("DICT",)io.Dict.Input("id")
("ARRAY",)io.Array.Input("id")
("COLORS",)io.Colors.Input("id")
("BOUNDING_BOXES",)io.BoundingBoxes.Input("id")
("RANGE",)io.Range.Input("id")
("HISTOGRAM",)io.Histogram.Input("id")
("POINT",)io.Point.Input("id")
("FACE_ANALYSIS",)io.FaceAnalysis.Input("id")
("BBOX",)io.BBOX.Input("id")
("SEGS",)io.SEGS.Input("id")
("IMAGECOMPARE",)io.ImageCompare.Input("id")
("LAYERS",)io.Layers.Input("id")
("COMPOSITOR",)io.Compositor.Input("id")
("CAMERA_INFO_STATE",)io.CameraInfoState.Input("id")
("VIDEO_EDIT",)io.VideoEdit.Input("id", features=["trim", "crop"])
("RESOLUTION_PREVIEW",)io.ResolutionPreview.Input("id")
("*",)io.AnyType.Input("id") or io.MultiType.Input("id", types=[...])

Method Migration

Execute Method

# V1: instance method with custom name
class V1Node:
    FUNCTION = "process"
    def process(self, image, value):
        return (result,)

# V3: classmethod named "execute", returns NodeOutput
class V3Node(io.ComfyNode):
    @classmethod
    def execute(cls, image, value):
        return io.NodeOutput(result)

IS_CHANGED → fingerprint_inputs

# V1
@classmethod
def IS_CHANGED(s, **kwargs):
    return float("NaN")  # always re-execute

# V3
@classmethod
def fingerprint_inputs(cls, **kwargs):
    import time
    return time.time()  # always re-execute

VALIDATE_INPUTS → validate_inputs

# V1
@classmethod
def VALIDATE_INPUTS(s, input_types=None, **kwargs):
    return True

# V3
@classmethod
def validate_inputs(cls, input_types=None, **kwargs):
    return True

check_lazy_status

# V1: instance method
def check_lazy_status(self, **kwargs):
    return ["input_name"]

# V3: classmethod
@classmethod
def check_lazy_status(cls, **kwargs):
    return ["input_name"]

Hidden Inputs

# V1: received as kwargs
def execute(self, image, unique_id=None, prompt=None):
    node_id = unique_id

# V3: accessed via cls.hidden
@classmethod
def execute(cls, image):
    node_id = cls.hidden.unique_id
    prompt = cls.hidden.prompt

Registration Migration

# V1
NODE_CLASS_MAPPINGS = {
    "Node1": Node1Class,
    "Node2": Node2Class,
}
NODE_DISPLAY_NAME_MAPPINGS = {
    "Node1": "Node One",
    "Node2": "Node Two",
}
WEB_DIRECTORY = "./js"

# V3
from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

class MyExtension(ComfyExtension):
    @override
    async def get_node_list(self) -> list[type[io.ComfyNode]]:
        return [Node1Class, Node2Class]

    @override
    async def on_load(self):
        # Optional: initialization logic
        pass

async def comfy_entrypoint() -> MyExtension:
    return MyExtension()

# WEB_DIRECTORY still works the same way for JS extensions
WEB_DIRECTORY = "./js"

Output Node Migration

# V1
class V1SaveNode:
    RETURN_TYPES = ()
    OUTPUT_NODE = True
    FUNCTION = "save"

    def save(self, images, prefix):
        # ... save logic ...
        return {"ui": {"images": results}}

# V3
from comfy_api.latest import io, ui

class V3SaveNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="V3SaveNode",
            display_name="Save",
            category="image",
            is_output_node=True,
            inputs=[
                io.Image.Input("images"),
                io.String.Input("prefix", default="output"),
            ],
            outputs=[],
            hidden=[io.Hidden.prompt, io.Hidden.extra_pnginfo],
        )

    @classmethod
    def execute(cls, images, prefix):
        saved = ui.ImageSaveHelper.get_save_images_ui(images, prefix, cls=cls)
        return io.NodeOutput(ui=saved)

Key Gotchas

  1. No instance state: V3 execute is a classmethod. Don't store state on self. Use external storage if needed.
  2. Fixed method name: Always execute, never custom names.
  3. Hidden access changed: Use cls.hidden.prompt not function parameters.
  4. Return type changed: io.NodeOutput(val) not (val,).
  5. Optional inputs: Use =None default in execute params, not separate "optional" dict.
  6. Async support: V3 execute can be async def execute(cls, ...).

See Also

  • comfyui-node-basics - V3 node fundamentals
  • comfyui-node-packaging - Project structure
  • comfyui-node-lifecycle - Execution lifecycle differences

ComfyUI Node Outputs

Nodes return data through io.NodeOutput. V3 provides built-in UI helpers for previews and file saving.

Basic Output

class SimpleNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="SimpleNode",
            display_name="Simple Node",
            category="example",
            inputs=[io.Float.Input("a"), io.Float.Input("b")],
            outputs=[
                io.Float.Output("SUM"),
                io.Float.Output("PRODUCT"),
            ],
        )

    @classmethod
    def execute(cls, a, b):
        # Values must match output order
        return io.NodeOutput(a + b, a * b)

Output Configuration

io.Schema(
    outputs=[
        io.Image.Output("IMAGE"),                    # basic output
        io.Int.Output("COUNT"),                      # integer output
        io.Float.Output("VALUE", display_name="Result"),  # custom display name
        io.String.Output("TEXT", tooltip="The processed text"),
        io.Image.Output("FRAMES", is_output_list=True),  # outputs a list
    ],
)

NodeOutput Variants

# Data only
return io.NodeOutput(image_tensor, mask_tensor)

# UI only (output node with no data outputs)
return io.NodeOutput(ui=ui.PreviewImage(images, cls=cls))

# Data + UI
return io.NodeOutput(image_tensor, ui=ui.PreviewImage(images, cls=cls))

# No output
return io.NodeOutput()

# Block execution
return io.NodeOutput(block_execution="Reason for blocking")

# Node expansion (positional args are outputs, not result= keyword)
return io.NodeOutput(output_ref, expand=graph.finalize())

UI Preview Helpers

Import ui from comfy_api.latest:

from comfy_api.latest import io, ui

PreviewImage

Display image previews on the node. Saves to temp directory automatically.

# Constructor: PreviewImage(image, animated=False, cls=None)
class PreviewNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="PreviewNode",
            display_name="Preview Image",
            category="image",
            is_output_node=True,
            inputs=[io.Image.Input("images")],
            outputs=[],
            hidden=[io.Hidden.prompt, io.Hidden.extra_pnginfo],
        )

    @classmethod
    def execute(cls, images):
        return io.NodeOutput(ui=ui.PreviewImage(images, cls=cls))

PreviewMask

# Constructor: PreviewMask(mask, animated=False, cls=None)
# Auto-converts mask to 3-channel grayscale for display
return io.NodeOutput(ui=ui.PreviewMask(masks, cls=cls))

PreviewAudio

# Constructor: PreviewAudio(audio, cls=None)
# Saves as FLAC to temp directory
return io.NodeOutput(ui=ui.PreviewAudio(audio, cls=cls))

PreviewVideo

# Constructor: PreviewVideo(values: list[SavedResult | dict])
return io.NodeOutput(ui=ui.PreviewVideo(saved_video_results))

PreviewText

Display text output:

return io.NodeOutput(ui=ui.PreviewText(value))

PreviewUI3D

Display 3D model preview:

return io.NodeOutput(ui=ui.PreviewUI3D(
    model_file=saved_result,   # SavedResult for the 3D file
    camera_info=camera_dict,   # camera position/target/zoom
    bg_image=image_tensor,     # optional background image (via **kwargs)
))

Saved3DModels (standard 3D output, v0.40+)

All core 3D save/preview nodes now report models as standard "3d" output items (shown in queue/assets like images):

# Constructor: Saved3DModels(results: list[SavedResult], camera_info=None, model_3d_info=None)
# -> {"3d": results, "camera_info": [camera_info], "model_3d_info": [...]}
return io.NodeOutput(ui=ui.Saved3DModels(
    [ui.SavedResult("model.glb", "", io.FolderType.output)],   # or FolderType.temp for previews
    camera_info=camera_dict,       # extended CameraInfo (quaternion/fov/near/far/frustum)
    model_3d_info=transforms,      # list[Model3DTransform]: position/quaternion/scale per model
))

ui.PreviewUI3DAdvanced(model_file, camera_info, model_3d_info, folder_type=None) still exists as a subclass, but model_file is now a relative path string ("subfolder/model.glb", default folder output) and it emits the "3d" format above, not {"result": [...]}.

Saving Images

Using ImageSaveHelper

The ui.ImageSaveHelper class provides static methods for various image formats:

# Save as PNG (returns list[SavedResult])
results = ui.ImageSaveHelper.save_images(
    images,                              # tensor [B,H,W,C]
    filename_prefix="ComfyUI",
    folder_type=io.FolderType.output,    # output, temp, or input
    cls=cls,                             # node class (for metadata)
    compress_level=4,
)

# Save and get UI object directly (saves to output folder)
saved_ui = ui.ImageSaveHelper.get_save_images_ui(images, "ComfyUI", cls=cls)
return io.NodeOutput(ui=saved_ui)

# Save animated PNG
result = ui.ImageSaveHelper.save_animated_png(
    images, "anim", io.FolderType.output, cls=cls, fps=12.0, compress_level=4
)

# Save animated PNG and get UI
saved_ui = ui.ImageSaveHelper.get_save_animated_png_ui(images, "anim", cls=cls, fps=12.0, compress_level=4)

# Save animated WebP
result = ui.ImageSaveHelper.save_animated_webp(
    images, "anim", io.FolderType.output, cls=cls,
    fps=12.0, lossless=False, quality=80, method=4
)

# Save animated WebP and get UI
saved_ui = ui.ImageSaveHelper.get_save_animated_webp_ui(
    images, "anim", cls=cls, fps=12.0, lossless=False, quality=80, method=4
)

Simple save node example:

class SaveImageNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="SaveImageNode",
            display_name="Save Image",
            category="image",
            is_output_node=True,
            inputs=[
                io.Image.Input("images"),
                io.String.Input("filename_prefix", default="ComfyUI"),
            ],
            outputs=[],
            hidden=[io.Hidden.prompt, io.Hidden.extra_pnginfo],
        )

    @classmethod
    def execute(cls, images, filename_prefix):
        saved = ui.ImageSaveHelper.get_save_images_ui(images, filename_prefix, cls=cls)
        return io.NodeOutput(ui=saved)

Manual Image Saving

import os
import json
import numpy as np
from PIL import Image as PILImage
from PIL.PngImagePlugin import PngInfo
import folder_paths

class CustomSaveNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="CustomSaveNode",
            display_name="Custom Save",
            category="image",
            is_output_node=True,
            inputs=[
                io.Image.Input("images"),
                io.String.Input("prefix", default="output"),
            ],
            outputs=[],
            hidden=[io.Hidden.prompt, io.Hidden.extra_pnginfo],
        )

    @classmethod
    def execute(cls, images, prefix):
        output_dir = folder_paths.get_output_directory()
        results = []

        for i, image in enumerate(images):
            # Convert tensor to PIL
            img_array = np.clip(255.0 * image.cpu().numpy(), 0, 255).astype(np.uint8)
            pil_image = PILImage.fromarray(img_array)

            # Add metadata
            metadata = PngInfo()
            if cls.hidden.prompt:
                metadata.add_text("prompt", json.dumps(cls.hidden.prompt))
            if cls.hidden.extra_pnginfo:
                for k, v in cls.hidden.extra_pnginfo.items():
                    metadata.add_text(k, json.dumps(v))

            # Save with counter
            filename = f"{prefix}_{i:05d}.png"
            filepath = os.path.join(output_dir, filename)
            pil_image.save(filepath, pnginfo=metadata)

            results.append(ui.SavedResult(
                filename=filename,
                subfolder="",
                type=io.FolderType.output,
            ))

        return io.NodeOutput(ui=ui.SavedImages(results))

Saving Audio

The ui.AudioSaveHelper supports FLAC, MP3, and Opus formats:

# Save audio (returns list[SavedResult])
results = ui.AudioSaveHelper.save_audio(
    audio,                               # {"waveform": Tensor, "sample_rate": int}
    filename_prefix="audio",
    folder_type=io.FolderType.output,
    cls=cls,
    format="flac",                       # "flac", "mp3", or "opus" (anything else raises ValueError)
    quality="128k",                      # MP3: "V0","128k","320k"; Opus: "64k"-"320k"
)

# Save and get UI object
saved_ui = ui.AudioSaveHelper.get_save_audio_ui(audio, "audio", cls=cls, format="flac", quality="128k")
return io.NodeOutput(ui=saved_ui)
class SaveAudioNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="SaveAudioNode",
            display_name="Save Audio",
            category="audio",
            is_output_node=True,
            inputs=[
                io.Audio.Input("audio"),
                io.String.Input("prefix", default="audio"),
                io.Combo.Input("format", options=["flac", "mp3", "opus"], default="flac"),
            ],
            outputs=[],
            hidden=[io.Hidden.prompt, io.Hidden.extra_pnginfo],
        )

    @classmethod
    def execute(cls, audio, prefix, format):
        saved = ui.AudioSaveHelper.get_save_audio_ui(audio, prefix, cls=cls, format=format)
        return io.NodeOutput(ui=saved)

Temporary Previews vs Permanent Saves

  • Previews (PreviewImage, etc.) save to the temp directory and are ephemeral
  • Saves (ImageSaveHelper.save_images) save to the output directory permanently
  • Use io.FolderType.temp, io.FolderType.output, or io.FolderType.input

How Core Post-Processes UI Output

After execute, every file entry ({"filename", "subfolder", "type"}) in the UI dict is enriched before it is sent/stored:

  • metadata: for image/video files, {"kind", "width", "height"} (+ duration, fps, frame_count for video) is added unless the entry already has metadata (v0.40+).
  • With the assets system on (default only in the Windows standalone build), id / preview_id are added; on a cache-hit replay id/preview_id are stripped from every dict entry, and an asset_preview key is consumed by core.
  • The UI dict is deep-copied each run.

So don't use id, preview_id, metadata or asset_preview as your own keys in UI entries, and keep UI values small and JSON-serializable.

V1 Output Patterns (Legacy Reference)

class V1SaveNode:
    RETURN_TYPES = ()
    OUTPUT_NODE = True
    FUNCTION = "save"

    def save(self, images, prefix):
        # ... save logic ...
        return {
            "ui": {
                "images": [
                    {"filename": "out.png", "subfolder": "", "type": "output"}
                ]
            }
        }

# Data + UI in V1:
class V1PreviewAndOutput:
    RETURN_TYPES = ("IMAGE",)
    OUTPUT_NODE = True
    FUNCTION = "run"

    def run(self, image):
        # ... preview logic ...
        return {
            "ui": {"images": [...]},
            "result": (processed_image,),
        }

See Also

  • comfyui-node-basics - Node structure and Schema
  • comfyui-node-datatypes - Data type formats
  • comfyui-node-lifecycle - Execution flow

ComfyUI Custom Node Packaging

How to structure, register, and publish a custom node package.

Project Structure

ComfyUI/custom_nodes/
  my_custom_nodes/
    __init__.py            # Entry point (required)
    nodes.py               # Node class definitions
    requirements.txt       # Python dependencies
    pyproject.toml         # Package metadata
    README.md              # Documentation
    js/                    # Frontend extensions (optional)
    │   └── my_extension.js
    docs/                  # Help pages (optional)
    │   └── MyNode.md
    locales/               # i18n translations (optional)
        └── zh/
            └── main.json

Entry Point: init.py

V3 Registration (Recommended)

# __init__.py
from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

from .nodes import MyNode1, MyNode2, MyNode3

WEB_DIRECTORY = "./js"  # optional: frontend JS extensions

class MyNodesExtension(ComfyExtension):
    @override
    async def get_node_list(self) -> list[type[io.ComfyNode]]:
        return [MyNode1, MyNode2, MyNode3]

    @override
    async def on_load(self):
        # Optional: run initialization logic when extension loads
        pass

async def comfy_entrypoint() -> MyNodesExtension:
    return MyNodesExtension()

V1 Registration (Legacy)

# __init__.py
from .nodes import MyNode1, MyNode2

NODE_CLASS_MAPPINGS = {
    "MyNode1": MyNode1,
    "MyNode2": MyNode2,
}

NODE_DISPLAY_NAME_MAPPINGS = {
    "MyNode1": "My Node 1",
    "MyNode2": "My Node 2",
}

WEB_DIRECTORY = "./js"

__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS", "WEB_DIRECTORY"]

Node Definitions File

# nodes.py
import torch
from comfy_api.latest import io

class MyNode1(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode1_UniqueID",   # globally unique
            display_name="My Node 1",
            category="my_nodes",
            description="Does something useful",
            inputs=[
                io.Image.Input("image"),
                io.Float.Input("value", default=1.0, min=0.0, max=10.0),
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def execute(cls, image, value):
        return io.NodeOutput(image * value)

Dependencies: requirements.txt

# requirements.txt
opencv-python>=4.8.0
requests>=2.28.0

Important: Only list dependencies not already included with ComfyUI. ComfyUI's requirements.txt includes: torch, torchvision, torchsde, numpy, einops, transformers, tokenizers, sentencepiece, safetensors, aiohttp, pyyaml, Pillow, scipy, tqdm, psutil, av (>=17), requests, blake3, plus non-essential kornia, spandrel, pydantic.

  • torchaudio is no longer a ComfyUI dependency (v0.38+) — list it yourself if you import it, or use core comfy.audio (resample, MelSpectrogram, bass_biquad, equalizer_biquad, treble_biquad). accelerate is not included either.
  • Officially supported minimum PyTorch is 2.7; Python 3.10 still works but logs an EOL warning.

pyproject.toml

[project]
name = "comfyui-my-nodes"
version = "1.0.0"
description = "My custom nodes for ComfyUI"
license = "MIT"
requires-python = ">=3.10"

[project.urls]
Repository = "https://github.com/username/comfyui-my-nodes"

Frontend Extensions (JavaScript)

Place .js files in the WEB_DIRECTORY:

my_custom_nodes/
  js/
    my_widgets.js      # Custom widget implementations
    my_extension.js    # Extension hooks
# __init__.py
WEB_DIRECTORY = "./js"

All .js files in this directory are loaded by the frontend automatically. CSS and other resources can be accessed at extensions/my_custom_nodes/filename.css.

Help Pages

Create markdown documentation per node:

my_custom_nodes/
  docs/
    MyNode1.md         # filename matches node_id
<!-- docs/MyNode1.md -->
# My Node 1

Processes images with adjustable value.

## Inputs
- **image**: The input image
- **value**: Processing strength (0.0 - 10.0)

## Outputs
- **IMAGE**: The processed image

Internationalization (i18n)

my_custom_nodes/
  locales/
    zh/
      main.json
      nodeDefs.json    # node definition translations
// locales/zh/nodeDefs.json
{
    "MyNode1_UniqueID": {
        "display_name": "我的节点1",
        "description": "处理图像",
        "inputs": {
            "image": { "display_name": "图像" },
            "value": { "display_name": "数值", "tooltip": "处理强度" }
        }
    }
}

Single-File Node

For very simple nodes, everything can be in one file:

# ComfyUI/custom_nodes/my_simple_node.py
import torch
from comfy_api.latest import ComfyExtension, io
from typing_extensions import override

class InvertImage(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="SimpleInvert",
            display_name="Simple Invert",
            category="image",
            inputs=[io.Image.Input("image")],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def execute(cls, image):
        return io.NodeOutput(1.0 - image)


class SimpleExtension(ComfyExtension):
    @override
    async def get_node_list(self):
        return [InvertImage]

async def comfy_entrypoint():
    return SimpleExtension()

Key Imports

# V3 API core
from comfy_api.latest import ComfyExtension, io, ui
from comfy_api.latest import ComfyAPI          # async runtime API (use with await)
from comfy_api.latest import ComfyAPISync      # sync runtime API (use in sync execute)
from comfy_api.latest import Input             # Input.Image, Input.Audio, Input.Mask, Input.Latent, Input.Video
from comfy_api.latest import InputImpl         # InputImpl.VideoFromFile, .VideoFromComponents, .VideoFromList
from comfy_api.latest import Types             # Types.MESH, Types.VOXEL, Types.File3D, Types.VideoCodec
from typing_extensions import override

# Common utilities
import folder_paths                            # directory management
from server import PromptServer                # server-to-client messaging
from comfy_execution.graph_utils import GraphBuilder  # node expansion

Using folder_paths

ComfyUI provides folder_paths for accessing standard directories:

import folder_paths

# Standard directories
input_dir = folder_paths.get_input_directory()
output_dir = folder_paths.get_output_directory()
temp_dir = folder_paths.get_temp_directory()

# Model directories
checkpoint_paths = folder_paths.get_folder_paths("checkpoints")
lora_paths = folder_paths.get_folder_paths("loras")

# Register custom model folder
folder_paths.add_model_folder_path("my_models", "/path/to/models")

# Get model file list
models = folder_paths.get_filename_list("checkpoints")
path = folder_paths.get_full_path_or_raise("checkpoints", name)   # resolve a combo value safely

# Path containment check before reading/writing user-supplied paths
folder_paths.is_within_directory(base_dir, candidate_path)

# Dataset files live in the "datasets" folder type (v0.30+)
dataset_dirs = folder_paths.get_folder_paths("datasets")

Publishing to ComfyUI Registry

1. Create pyproject.toml

[project]
name = "comfyui-my-nodes"
version = "1.0.0"
description = "My custom nodes"
license = "MIT"

[tool.comfy]
PublisherId = "your-publisher-id"

2. Publish

comfy node publish

CI/CD with GitHub Actions

# .github/workflows/publish.yml
name: Publish to ComfyUI Registry
on:
  push:
    tags:
      - 'v*'
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install comfy-cli
      - run: comfy node publish
        env:
          COMFY_API_KEY: ${{ secrets.COMFY_API_KEY }}

Scaffolding with comfy-cli

# Install comfy-cli
pip install comfy-cli

# Create new custom node project
cd ComfyUI/custom_nodes
comfy node scaffold

This generates the boilerplate structure with all necessary files.

Node ID Best Practices

  • Use a globally unique prefix: "MyProject_NodeName" or "username.NodeName"
  • A node_id that collides with a core node is ignored entirely — class and display name (v0.35+)
  • Never change node_id after release (breaks saved workflows)
  • Use display_name for user-facing name changes
  • Use search_aliases for discoverability: search_aliases=["alias1", "alias2"]

Common Patterns

Organizing Multiple Node Files

# __init__.py
from typing_extensions import override
from comfy_api.latest import ComfyExtension, io

from .image_nodes import BlurNode, SharpenNode, ResizeNode
from .text_nodes import ConcatNode, FormatNode
from .util_nodes import SwitchNode, DebugNode

class MyExtension(ComfyExtension):
    @override
    async def get_node_list(self):
        return [
            BlurNode, SharpenNode, ResizeNode,
            ConcatNode, FormatNode,
            SwitchNode, DebugNode,
        ]

async def comfy_entrypoint():
    return MyExtension()

Conditional Node Loading

class MyExtension(ComfyExtension):
    @override
    async def get_node_list(self):
        nodes = [BasicNode]
        try:
            import cv2
            from .opencv_nodes import OpenCVNode
            nodes.append(OpenCVNode)
        except ImportError:
            pass
        return nodes

Deployment Constraints

  • Disabled nodes: users can prune node IDs with --disabled-nodes-config file.yaml (disabled_nodes: [ids]), and --disable-partner-nodes / --offline (the old --disable-api-nodes is a deprecated alias of --offline). Don't assume another pack's (or a partner) node exists, e.g. in GraphBuilder expansions.
  • Governed builds (v0.40+, organization policy builds only) pin packs by a BLAKE3 digest of their .py/.pyw/.pyd/.so/.dll/.dylib/.js/.mjs files and refuse packs that contain __pycache__/.pyc files or symlinks. Ship source only, and never rewrite or auto-update your own code files at runtime.

See Also

  • comfyui-node-basics - Node class structure
  • comfyui-node-frontend - JavaScript extension details
  • comfyui-node-migration - V1 to V3 migration

Sponsors

Details

Marketplace
jtydhr88/comfyui-custom-node-skills
Source
plugins/comfyui-custom-nodes
Category
Community