Introducing a new way to review your PRs.

Read the announcement

comfy-org / comfyui

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / core-node-registry-and-builtins

Core Node Registry and Built-ins

Overview

This area defines the base application's node registry and the built-in node classes exposed before extension loading. The main registry lives in nodes.py: NODE_CLASS_MAPPINGS maps workflow class_type strings to Python classes, and NODE_DISPLAY_NAME_MAPPINGS supplies UI names for selected ids. The same file also owns node discovery for built-in extras, API nodes, and external custom nodes, plus the core built-in implementations for model loading, conditioning, latent/image transforms, sampling, image/latent I/O, and output nodes.

Node classes in nodes.py follow the V1 node contract used by the server and executor. Each node exposes a classmethod INPUT_TYPES() returning required, optional, and/or hidden input metadata; RETURN_TYPES and optional RETURN_NAMES/OUTPUT_TOOLTIPS; FUNCTION, the method name to call; and metadata such as CATEGORY, DESCRIPTION, SEARCH_ALIASES, DEPRECATED, EXPERIMENTAL, ESSENTIALS_CATEGORY, and OUTPUT_NODE. Output nodes such as SaveImage and SaveLatent set OUTPUT_NODE = True, return both UI payloads and result tuples, and use hidden prompt/extra_pnginfo inputs for metadata embedding. Loader nodes derive selectable values from folder_paths.get_filename_list(...) and resolve files with folder_paths.get_full_path_or_raise(...).

The base built-ins registered in NODE_CLASS_MAPPINGS include the usual generation path: CheckpointLoaderSimple, CLIPTextEncode, EmptyLatentImage, KSampler, VAEDecode, and SaveImage. common_ksampler() in nodes.py is the shared implementation for KSampler and KSamplerAdvanced: it normalizes latent channel counts, prepares seeded noise or empty noise, forwards any noise_mask, builds a preview callback through latent_preview.prepare_callback(), calls comfy.sample.sample(...), and returns the updated latent dictionary after dropping temporary downscale-ratio hints. Latent dictionaries conventionally carry at least samples, and may also carry fields such as noise_mask, batch_index, downscale_ratio_spacial, or downscale_ratio_temporal that specific nodes preserve or consume.

load_custom_node() in nodes.py is the shared importer for extension-style modules. For V1 modules, it reads module-level NODE_CLASS_MAPPINGS and optional NODE_DISPLAY_NAME_MAPPINGS, merges entries that are not in the ignore set, and annotates classes with RELATIVE_PYTHON_MODULE. For V3 extensions, it calls a comfy_entrypoint, expects a ComfyExtension, awaits on_load(), asks get_node_list(), reads each class schema through GET_SCHEMA(), and registers by schema.node_id. EXTENSION_WEB_DIRS is populated from pyproject.toml tool.comfy.web metadata or a module WEB_DIRECTORY, while LOADED_MODULE_DIRS records successfully loaded module directories for management routes.

Initialization is layered in nodes.py. init_extra_nodes() first registers public API versions, then calls init_builtin_extra_nodes() to import a fixed list from comfy_extras/, then init_builtin_api_nodes() for comfy_api_nodes/nodes_*.py, and finally init_external_custom_nodes() unless disabled. External custom loading scans folder_paths.get_folder_paths("custom_nodes"), skips non-Python files, .disabled entries, disabled/whitelist-filtered modules, manager-blocked modules, and governance-refused packs. It passes the base registry names as ignore, so custom nodes cannot replace base built-in ids. Built-in extra and API nodes are loaded through the same import path without that base ignore set.

node_helpers.py contains small conventions that many built-ins rely on. conditioning_set_values() copies each conditioning entry's metadata dict before setting or appending keys, which is how area masks, ControlNet handles, inpaint latents, timestep bounds, unCLIP data, and scaled pooled outputs are attached without mutating upstream conditioning entries. conditioning_set_values_with_timestep_range() splits conditioning entries around an intersection range and uses a small epsilon to avoid overlapping sampler gates. pillow() retries selected PIL operations with ImageFile.LOAD_TRUNCATED_IMAGES enabled for truncated or malformed image files. hasher() selects the configured hash implementation for server-side upload duplicate checks, string_to_torch_dtype() maps common dtype strings, and image_alpha_fix() aligns RGB/RGBA tensors before compositing/batching-style operations.

latent_preview.py owns sampler preview generation. prepare_callback(model, steps, x0_output_dict=None) creates a comfy.utils.ProgressBar, chooses a previewer with get_previewer(model.load_device, model.model.latent_format), optionally stores the latest denoised x0, decodes nested latents when needed, and passes (format, PIL image, max_resolution) preview tuples to ProgressBar.update_absolute(...). Previewer selection is controlled by args.preview_method: NoPreviews disables it, Auto falls back to Latent2RGB, TAESD loads a matching decoder from models/vae_approx, and any remaining path uses latent_format.latent_rgb_factors when available. Video TAESD names use VAE via TAEHVPreviewerImpl; image TAESD names use TAESDPreviewerImpl; both produce JPEG-oriented RGB previews.

The execution layer consumes the registry directly. In execution.py, prompt validation resolves each workflow node's class_type through nodes.NODE_CLASS_MAPPINGS, reads INPUT_TYPES()/RETURN_TYPES, checks linked output types, detects OUTPUT_NODE roots, calls optional VALIDATE_INPUTS or V3 validate_inputs, and computes cache fingerprints through IS_CHANGED or V3 fingerprint_inputs. Execution calls nodes.before_node_execution() before interruptible node invocations, which delegates to comfy.model_management.throw_exception_if_processing_interrupted(), and server interrupt routes eventually call nodes.interrupt_processing() to flip the model-management interrupt flag.

The server layer exposes the registry to clients. In server.py, /object_info and /object_info/{node_class} iterate nodes.NODE_CLASS_MAPPINGS and serialize each node's inputs, output types, list flags, display name, description, category, output-node flag, deprecation/experimental/dev/API flags, search aliases, and essentials category. /extensions and static route setup read nodes.EXTENSION_WEB_DIRS so web assets contributed by loaded modules are discoverable under /extensions/{name}/....

Routing/covers for index: use this doc for changes to nodes.py, node_helpers.py, or latent_preview.py, especially edits to base node classes, registry mappings, node import/discovery, extension web directories, node helper conventions, sampler callbacks, and latent preview selection/decoding.

Coupling

  • If a node id, RETURN_TYPES, FUNCTION, OUTPUT_NODE, or INPUT_TYPES() shape changes in nodes.py, verify execution.py prompt validation/execution and server.py /object_info serialization still agree with the V1 node contract; both consume these class attributes by name and do not have a separate schema for V1 nodes.
  • If NODE_CLASS_MAPPINGS or load_custom_node() registration behavior changes in nodes.py, verify custom-node collision behavior remains intentional: init_external_custom_nodes() passes base node names as ignore, but init_builtin_extra_nodes() and init_builtin_api_nodes() do not.
  • If hidden inputs are added to V1 nodes in nodes.py, verify execution.py.get_input_data() recognizes the hidden token string; unrecognized hidden values will not be injected into the node call.
  • If conditioning metadata keys are changed in node_helpers.py or any nodes.py conditioning node, verify sampler/model code that reads keys such as area, mask, mask_strength, control, concat_latent_image, concat_mask, start_percent, and end_percent; these are plain dictionary keys with no central schema.
  • If latent preview formats or payloads change in latent_preview.py, verify nodes.py.common_ksampler() and comfy.utils.ProgressBar.update_absolute(...) still expect the same callback behavior and preview tuple shape.
  • If EXTENSION_WEB_DIRS population changes in nodes.py, verify server.py /extensions and static route setup still use matching names and paths; the server reads the dictionary populated during node import.

Risks

  • nodes.py and execution.py share stringly-typed node contracts. If a V1 node's FUNCTION does not match a method name or its RETURN_TYPES length disagrees with returned tuples, validation and execution can fail at runtime after the node has already appeared in /object_info.
  • Conditioning metadata in node_helpers.py is copied shallowly. If a node stores mutable nested objects and a later node mutates them in place, upstream or sibling conditioning branches can observe unintended changes because only the outer metadata dict is copied.
  • latent_preview.py silently falls back from requested TAESD previews to latent-RGB previews when no TAESD decoder is found. If a latent format has incorrect latent_rgb_factors, previews can be misleading while sampling output remains correct.