The Node System is the backbone of ComfyUI, defining reusable computational units called nodes. These nodes are connected in a graph to compose complex AI workflows for image, audio, video, 3D, and model processing. This system manages the lifecycle of a node from declaration and registration to data input validation and execution.
Key features include:
INPUT_TYPES and the modern V3 define_schema patterns.IO enums and structured schema classes.NODE_CLASS_MAPPINGS and the ComfyExtension interface.NodeReplaceManager to handle node evolution.ComfyUI provides two primary base classes for node development, representing the evolution of the framework.
| Base Class | API Version | Definition Site | Key Mechanism |
|---|---|---|---|
ComfyNodeABC | Legacy | comfy/comfy_types/node_typing.py29 | Uses class attributes like INPUT_TYPES and RETURN_TYPES. |
ComfyNode | V3 | comfy_api/latest/io.py32 | Uses a declarative define_schema() method returning an io.Schema object. |
ComfyNodeABC)Legacy nodes define their interface using class-level attributes. The execution engine calls the method specified by the FUNCTION string.
Example: CLIPTextEncode nodes.py56-78
INPUT_TYPES(): Returns an InputTypeDict defining required, optional, and hidden inputs nodes.py57-64RETURN_TYPES: A tuple of strings or IO enum values nodes.py65FUNCTION: The name of the method to execute (e.g., "encode") nodes.py67ComfyNode)The modern API utilizes a more structured approach, wrapping metadata and I/O definitions into a single Schema object.
Example: LatentAdd comfy_extras/nodes_latent.py19-44
define_schema(): Returns io.Schema containing node_id, inputs, and outputs comfy_extras/nodes_latent.py21-33execute(): The primary logic method (replaces the need for a FUNCTION string attribute) comfy_extras/nodes_latent.py35-44Diagram: Node Class Hierarchy and Metadata Flow
Sources: nodes.py56-78 comfy/comfy_types/node_typing.py29 comfy_extras/nodes_latent.py19-44
The system uses the IO enum to standardize data types across the graph. This ensures that a LATENT output from a sampler can only connect to a LATENT input on a VAE decoder.
Standard Types comfy/comfy_types/node_typing.py16-53
STRING, INT, FLOAT, BOOLEAN.MODEL, CLIP, VAE, CONDITIONING, LATENT.IMAGE, MASK, AUDIO, VIDEO.ANY ("*"), which matches any type comfy/comfy_types/node_typing.py54-58The V3 API introduces structured input types via comfy_api.latest.io which provide richer metadata than simple strings.
Diagram: Type Taxonomy and Code Association
Sources: comfy/comfy_types/node_typing.py16-72 comfy_api/latest/io.py32
INPUT_TYPESThe INPUT_TYPES dictionary structure allows for detailed widget configuration:
default: The initial value.min/max/step: Constraints for numeric inputs comfy/comfy_types/node_typing.py131-136multiline: Boolean to toggle a larger text area in the UI comfy/comfy_types/node_typing.py147-148tooltip: Documentation shown on hover comfy/comfy_types/node_typing.py118-119define_schemaV3 schemas use explicit objects for inputs like io.Latent.Input or io.Float.Input. This allows for advanced features like MultiType and MatchType.
Example: LatentInterpolate Schema comfy_extras/nodes_latent.py98-112
Sources: nodes.py58-64 comfy/comfy_types/node_typing.py96-174 comfy_extras/nodes_latent.py98-112
Nodes are registered with the system to be visible to the frontend and available for execution.
NODE_CLASS_MAPPINGS and NODE_DISPLAY_NAME_MAPPINGS dictionaries.ComfyExtension interface comfy_api/latest/io.py32 allows for modular node pack registration.register_versions to track API compatibility nodes.py30-31Diagram: Node Discovery and Registration Workflow
Sources: nodes.py30-32 comfy_api/latest/io.py32
Nodes often interact with underlying model weights through the patching system.
load_lora_for_models clones the model and applies weight offsets comfy/sd.py92-124load_bypass_lora_for_models injects LoRA computation into the forward pass using BypassInjectionManager, avoiding direct modification of base weights comfy/sd.py127-186CLIPTextEncode transform raw text into the CONDITIONING format required by diffusion models nodes.py73-77Sources: comfy/sd.py92-186 nodes.py73-77
As nodes evolve, the NodeReplaceManager (part of the core server architecture) handles the migration of old node versions to new ones in existing workflows.
INPUT_TYPES and converts them to the internal representation used by the execution engine comfy_execution/graph.py64-104UNIQUE_ID in hidden inputs to allow nodes to track their own identity within a graph comfy_execution/caching.py19-24Sources: comfy_execution/graph.py64-104 comfy_execution/caching.py19-24
Refresh this wiki