/comfyui-node-migration

name: comfyui-node-migration
description: ComfyUI V1 to V3 node migration - converting legacy nodes to the V3 API. Use when migrating existing custom nodes from V1 to V3, understanding differences between API versions, or modernizing node code.

ComfyUI V1 → V3 Migration Guide

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

Migration Checklist

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

Side-by-Side Comparison

V1 (Before)

import torch

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

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

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

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

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

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

V3 (After)

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

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

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

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

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

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


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

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

Property Mapping

| V1 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