
comfyui-custom-nodes
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-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add jtydhr88/comfyui-custom-node-skills.
Contents
Discovered from sourceSkills 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
minare required; aboveminare 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:
DynamicSlotis registered infrastructure incomfy_api.latestbut 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 fromio; do not import it fromcomfy_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_idis 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,accumulatenot 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=Truein Schema - Use
GraphBuilderto 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 newInputMapSetValue:{"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 fundamentalscomfyui-node-inputs- Basic input typescomfyui-node-lifecycle- Execution lifecycle and cachingcomfyui-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:
- Inherit from
io.ComfyNode define_schema(cls)- classmethod returningio.Schemaexecute(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
| Aspect | V3 | V1 |
|---|---|---|
| Base class | io.ComfyNode | Plain class |
| Execute method | execute classmethod (fixed name) | Instance method (custom name via FUNCTION) |
| Inputs | io.Schema(inputs=[...]) | INPUT_TYPES() dict |
| Outputs | io.Schema(outputs=[...]) | RETURN_TYPES tuple |
| Return value | io.NodeOutput(...) | Plain tuple |
| Registration | ComfyExtension + comfy_entrypoint() | NODE_CLASS_MAPPINGS dict |
| State | No instance state (classmethods) | Instance state allowed |
| Hidden inputs | cls.hidden.prompt, etc. | kwargs from "hidden" dict |
Important Rules
node_idmust be globally unique across all nodesexecute()parameters must match input IDs exactly- All methods are
@classmethodin 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 detailscomfyui-node-outputs- Output types and UI outputscomfyui-node-packaging- Project structure and packagingcomfyui-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
| Type | V3 Class | Format | Description |
|---|---|---|---|
| IMAGE | io.Image | torch.Tensor [B,H,W,C] float32 0-1 | Batch of RGB images |
| MASK | io.Mask | torch.Tensor [H,W] or [B,H,W] float32 0-1 | Grayscale masks |
| LATENT | io.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) |
| CONDITIONING | io.Conditioning | list[tuple[Tensor, PooledDict]] | Text conditioning with pooled outputs |
| AUDIO | io.Audio | {"waveform": Tensor[B,C,T], "sample_rate": int} | Audio data |
| VIDEO | io.Video | VideoInput ABC | Video data (abstract base class) |
| SIGMAS | io.Sigmas | torch.Tensor 1D, length steps+1 | Noise schedule |
| NOISE | io.Noise | Object with generate_noise() | Noise generator |
| LORA_MODEL | io.LoraModel | dict[str, torch.Tensor] | LoRA weight deltas |
| LOSS_MAP | io.LossMap | {"loss": list[torch.Tensor]} | Loss map |
| TRACKS | io.Tracks | {"track_path": Tensor, "track_visibility": Tensor} | Motion tracking data |
| WAN_CAMERA_EMBEDDING | io.WanCameraEmbedding | torch.Tensor | WAN camera embeddings |
| LATENT_OPERATION | io.LatentOperation | Callable[[Tensor], Tensor] | Latent transform function |
| TIMESTEPS_RANGE | io.TimestepsRange | tuple[int, int] | Range 0.0-1.0 |
| DICT | io.Dict | dict | Generic dictionary |
| ARRAY | io.Array | list | Generic list/array |
| LAYERS | io.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)
| Type | V3 Class | Python Type |
|---|---|---|
| MODEL | io.Model | ModelPatcher |
| CLIP | io.Clip | CLIP |
| VAE | io.Vae | VAE |
| CONTROL_NET | io.ControlNet | ControlNet |
| CLIP_VISION | io.ClipVision | ClipVisionModel |
| CLIP_VISION_OUTPUT | io.ClipVisionOutput | ClipVisionOutput |
| STYLE_MODEL | io.StyleModel | StyleModel |
| GLIGEN | io.Gligen | ModelPatcher (wrapping Gligen) |
| UPSCALE_MODEL | io.UpscaleModel | ImageModelDescriptor |
| BACKGROUND_REMOVAL | io.BackgroundRemoval | BackgroundRemovalModel (e.g. BiRefNet) |
| LATENT_UPSCALE_MODEL | io.LatentUpscaleModel | Any |
| SAMPLER | io.Sampler | Sampler |
| GUIDER | io.Guider | CFGGuider |
| HOOKS | io.Hooks | HookGroup |
| HOOK_KEYFRAMES | io.HookKeyframes | HookKeyframeGroup |
| MODEL_PATCH | io.ModelPatch | Any |
| AUDIO_ENCODER | io.AudioEncoder | Any |
| AUDIO_ENCODER_OUTPUT | io.AudioEncoderOutput | Any |
| PHOTOMAKER | io.Photomaker | Any |
| POINT | io.Point | Any |
| FACE_ANALYSIS | io.FaceAnalysis | Any |
| BBOX | io.BBOX | Any |
| SEGS | io.SEGS | Any |
3D Types
| Type | V3 Class | Python Type | Description |
|---|---|---|---|
| MESH | io.Mesh | MESH(vertices, faces) | 3D mesh with vertices + faces tensors |
| VOXEL | io.Voxel | VOXEL(data) | Voxel data tensor |
| SPLAT | io.Splat | SPLAT | Gaussian splat data |
| FILE_3D | io.File3DAny | File3D | Any supported 3D format |
| FILE_3D_GLB | io.File3DGLB | File3D | Binary glTF |
| FILE_3D_GLTF | io.File3DGLTF | File3D | JSON-based glTF |
| FILE_3D_FBX | io.File3DFBX | File3D | FBX format |
| FILE_3D_OBJ | io.File3DOBJ | File3D | OBJ format |
| FILE_3D_STL | io.File3DSTL | File3D | STL format (3D printing) |
| FILE_3D_USDZ | io.File3DUSDZ | File3D | Apple AR format |
| FILE_3D_PLY | io.File3DPLY | File3D | PLY (point cloud / splat) |
| FILE_3D_SPLAT | io.File3DSPLAT | File3D | .splat gaussian splat file |
| FILE_3D_SPZ | io.File3DSPZ | File3D | Compressed splat (.spz) |
| FILE_3D_KSPLAT | io.File3DKSPLAT | File3D | .ksplat format |
| FILE_3D_SPLAT_ANY | io.File3DSplatAny | File3D | Any splat format |
| FILE_3D_POINT_CLOUD_ANY | io.File3DPointCloudAny | File3D | Any point cloud format |
| SVG | io.SVG | SVG | Scalable vector graphics |
| LOAD_3D | io.Load3D | Model3DDict (see below) | 3D model with renders |
| LOAD_3D_ANIMATION | io.Load3DAnimation | Same as Load3D | Animated 3D model |
| LOAD3D_CAMERA | io.Load3DCamera | CameraInfo (see below) | 3D camera info |
| LOAD3D_MODEL_INFO | io.Load3DModelInfo | list[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)
| Type | V3 Class | Python Type | Description |
|---|---|---|---|
| INT | io.Int | int | Integer with min/max/step |
| FLOAT | io.Float | float | Float with min/max/step/round |
| STRING | io.String | str | Text (single/multi-line) |
| BOOLEAN | io.Boolean | bool | Toggle with labels |
| COMBO | io.Combo | str | Dropdown selection |
| COMBO (multi) | io.MultiCombo | list[str] | Multi-select dropdown |
| COLOR | io.Color | str (hex) | Color picker, default #ffffff |
| COLORS | io.Colors | list[str] (hex) | Color palette (list of colors) |
| BOUNDING_BOX | io.BoundingBox | {"x": int, "y": int, "width": int, "height": int} | Rectangle region |
| BOUNDING_BOXES | io.BoundingBoxes | list[{"x", "y", "width", "height", "metadata": dict}] | Multiple labeled regions |
| CURVE | io.Curve | list[tuple[float, float]] | Spline curve points |
| RANGE | io.Range | RangeInput (min/max + optional midpoint) | Levels/range editor with gradient display |
| IMAGECOMPARE | io.ImageCompare | dict | Image comparison widget |
| WEBCAM | io.Webcam | str | Webcam capture widget |
| HISTOGRAM | io.Histogram | list[int] | Histogram bin counts |
| VIDEO_EDIT | io.VideoEdit | {"trim"?: {start_time, duration}, "crop"?: {x, y, width, height}} | Video trim/crop editor (features=["trim","crop"]) |
| RESOLUTION_PREVIEW | io.ResolutionPreview | dict | Live resolution preview bound to other widgets by name |
| COMPOSITOR | io.Compositor | dict (LayerState) | Layer-editor state, default {} |
| CAMERA_INFO_STATE | io.CameraInfoState | dict | Camera editor state (input only) |
Special Types
| Type | V3 Class | Description |
|---|---|---|
* (ANY) | io.AnyType | Matches any type |
| COMFY_MULTITYPED_V3 | io.MultiType | Accept multiple specific types on one input |
| COMFY_MATCHTYPE_V3 | io.MatchType | Generic type matching across inputs/outputs |
| COMFY_AUTOGROW_V3 | io.Autogrow | Dynamic growing inputs |
| COMFY_DYNAMICCOMBO_V3 | io.DynamicCombo | Combo that reveals sub-inputs per option |
| COMFY_DYNAMICSLOT_V3 | io.DynamicSlot | Connection 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_CONTROL | io.FlowControl | Internal testing only |
| ACCUMULATION | io.Accumulation | Internal 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 tensorsVideoFromList(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 registrationcomfyui-node-inputs- Input configuration details (widget options)comfyui-node-outputs- Output types and UI outputscomfyui-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 splicingnode.widgets. node.widgetsmay beundefineduntil first assigned:node.widgets ??= [],node.widgets?.length ?? 0.- Create widgets via
addWidget/addCustomWidget/addDOMWidget(or aBaseWidgetsubclass). A plain object pushed ontonode.widgetsis 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"]ondocument.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.linksdeprecated (v1.53+) — reads still work but warn and may lag the graph. Writes no longer change links, except thatinput.link = nulldisconnects. Usenode.isInputConnected(i),node.getInputLink(i),node.isOutputConnected(i),node.getOutputNodes(i),node.connect(),node.disconnectInput(i). Thenode:slot-links:changedandnode:slot-errors:changedgraph events are removed. For add/remove notifications with several subscribers, usegraph.events.addEventListener("node:added" | "node:before-removed" | "node:removed", ...).onConfigure(data)receives a shallow copy (v1.55.2+) — changing top-level keys ofdatahas no effect. Persist custom state innode.properties/graph.extra.- Core node fields are accessors (v1.53+) —
id,type,title,mode,flags,color,bgcolor,shapeno longer appear inObject.keys(node)/{...node}; usenode.serialize(). Changingnode.typeafter construction warns. node.sizeis the requested size —getBounding()/boundingRectgive the rendered footprint (can be larger).canvas.repositionNodesVueMode()→canvas.applyNodePositions()(old name kept as deprecated alias).canvas.selected_nodesdeprecated (upcoming) — warns and returns a snapshot. Readcanvas.selectedItems(a snapshot Set; re-read it afteradd/delete) and change the selection withcanvas.selectItems(items, addToCurrent?).- Minor deprecations —
node.badgePosition(badges always render top-right; assignment is ignored),node.widgets_up(usewidgets_start_y),options.canvasOnly(useoptions.surfaces). - Group nodes removed — group nodes can no longer be created; workflows containing them auto-convert to subgraphs on load.
GroupNodeHandler/GroupNodeConfigremain re-exported for backward compatibility only. Use subgraphs for new work. LiteGraph.use_uuidsremoved — node IDs are always numeric. Don't read or set this flag (UUIDs are still used internally for subgraph/slot IDs).LGraph.onGetNodeMenuOptionsremoved;LGraph.onBeforeChangedeprecated — assigning it still works but warns; useLGraphCanvas.onBeforeChangeinstead.IBaseWidget.entityIdremoved — widget identity is thewidgetIdbranded key (graphId:nodeId:name); promoted subgraph widgets are store-backed.node.sizeis Proxy-backed — bothnode.size[1] = handnode.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
| Level | Modules | Notes |
|---|---|---|
| Stable | scripts/app, scripts/api | Guaranteed public API |
| Internal (console warning) | scripts/widgets, scripts/domWidget, scripts/utils, scripts/pnginfo, scripts/changeTracker, scripts/defaultGraph, scripts/metadata/* | Usable but may change |
| Deprecated | scripts/ui | Will be removed; use Vue alternatives |
Key Modules
scripts/api—ComfyApiclass:fetchApi(),queuePrompt(),getNodeDefs(), WebSocket events, settings, user data, system statsscripts/app—ComfyAppsingleton (app): graph operations,registerExtension(),extensionManager, clipboard, coordinate conversionscripts/widgets—ComfyWidgetsregistry (INT, FLOAT, STRING, BOOLEAN, COMBO, IMAGEUPLOAD, etc.),addValueControlWidget(s)(),updateControlWidgetLabel()(IS_CONTROL_WIDGETno longer exported since v1.58)scripts/domWidget—addDOMWidget(),DOMWidgetImpl,ComponentWidgetImpl(Vue component wrapper)scripts/utils—clone(),addStylesheet(),uploadFile(), storage helpersscripts/pnginfo—getPngMetadata(),getWebpMetadata(),importA1111(), format-specific extractors
For full API details, see the API Reference.
See Also
comfyui-node-basics- Backend node structurecomfyui-node-packaging- Project structure with JS extensionscomfyui-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 incomfyui-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 (seecomfyui-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 overviewcomfyui-node-datatypes- Data type detailscomfyui-node-advanced- MatchType, Autogrow, DynamicCombocomfyui-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:
- Identifies output nodes (
is_output_node=True) - Builds dependency graph
- Topological sort determines execution order
- 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 asexecute() - 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_inputsis 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=Truedoes 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 implementfingerprint_inputs(V3) orIS_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'sworkflow_metadata(e.g.workflow_id) merged in (v0.40+) — includeprompt_idso 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 fundamentalscomfyui-node-inputs- Input types and lazy evaluationcomfyui-node-advanced- Expansion, MatchType, DynamicCombocomfyui-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
- Change base class to
io.ComfyNode - Replace
INPUT_TYPES()withdefine_schema()returningio.Schema - Rename execution function to
executeand make it a@classmethod - Replace return tuples with
io.NodeOutput(...) - Replace
IS_CHANGEDwithfingerprint_inputs - Replace
VALIDATE_INPUTSwithvalidate_inputs - Convert
check_lazy_statusto@classmethod - Replace
NODE_CLASS_MAPPINGSwithComfyExtension+comfy_entrypoint() - Access hidden inputs via
cls.hiddeninstead of kwargs - 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 Property | V3 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 = True | io.Schema(is_output_node=True) |
DEPRECATED = True | io.Schema(is_deprecated=True) |
EXPERIMENTAL = True | io.Schema(is_experimental=True) |
API_NODE = True | io.Schema(is_api_node=True) |
NOT_IDEMPOTENT = True | io.Schema(not_idempotent=True) |
DESCRIPTION = "..." | io.Schema(description="...") |
SEARCH_ALIASES = [...] | io.Schema(search_aliases=[...]) |
INPUT_IS_LIST = True | io.Schema(is_input_list=True) |
OUTPUT_IS_LIST = (True,) | io.Image.Output(is_output_list=True) |
DEV_ONLY = True | io.Schema(is_dev_only=True) |
ESSENTIALS_CATEGORY = "Basic" | io.Schema(essentials_category="Basic") |
Input Type Mapping
| V1 Input | V3 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
- No instance state: V3 execute is a classmethod. Don't store state on
self. Use external storage if needed. - Fixed method name: Always
execute, never custom names. - Hidden access changed: Use
cls.hidden.promptnot function parameters. - Return type changed:
io.NodeOutput(val)not(val,). - Optional inputs: Use
=Nonedefault in execute params, not separate"optional"dict. - Async support: V3 execute can be
async def execute(cls, ...).
See Also
comfyui-node-basics- V3 node fundamentalscomfyui-node-packaging- Project structurecomfyui-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
tempdirectory and are ephemeral - Saves (ImageSaveHelper.save_images) save to the
outputdirectory permanently - Use
io.FolderType.temp,io.FolderType.output, orio.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_countfor video) is added unless the entry already hasmetadata(v0.40+).- With the assets system on (default only in the Windows standalone build),
id/preview_idare added; on a cache-hit replayid/preview_idare stripped from every dict entry, and anasset_previewkey 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 Schemacomfyui-node-datatypes- Data type formatscomfyui-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.
torchaudiois no longer a ComfyUI dependency (v0.38+) — list it yourself if you import it, or use corecomfy.audio(resample,MelSpectrogram,bass_biquad,equalizer_biquad,treble_biquad).accelerateis 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_idthat collides with a core node is ignored entirely — class and display name (v0.35+) - Never change
node_idafter release (breaks saved workflows) - Use
display_namefor user-facing name changes - Use
search_aliasesfor 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-nodesis a deprecated alias of--offline). Don't assume another pack's (or a partner) node exists, e.g. inGraphBuilderexpansions. - Governed builds (v0.40+, organization policy builds only) pin packs by a BLAKE3 digest of their
.py/.pyw/.pyd/.so/.dll/.dylib/.js/.mjsfiles and refuse packs that contain__pycache__/.pycfiles or symlinks. Ship source only, and never rewrite or auto-update your own code files at runtime.
See Also
comfyui-node-basics- Node class structurecomfyui-node-frontend- JavaScript extension detailscomfyui-node-migration- V1 to V3 migration
Sponsors
Details
- Marketplace
- jtydhr88/comfyui-custom-node-skills
- Source
- plugins/comfyui-custom-nodes
- Category
- Community