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 / extra-nodes-and-extensions

Extra Nodes and Extension Packages

Overview

comfy_extras/** is ComfyUI's built-in optional node collection. These nodes are not part of the minimal core graph, but nodes.py loads them at startup through init_builtin_extra_nodes(), which imports an explicit ordered list of comfy_extras/nodes_*.py files with module_parent="comfy_extras". Import failures are collected and reported as missing optional dependencies rather than aborting the whole application, so a new extra node file only becomes available when it is added to that list.

Most files use the V3 extension pattern: node classes subclass comfy_api.latest.io.ComfyNode or IO.ComfyNode, define schemas with typed inputs/outputs, then expose a ComfyExtension whose get_node_list() returns the classes and whose comfy_entrypoint() returns the extension. Examples include comfy_extras/nodes_video.py, comfy_extras/nodes_audio.py, comfy_extras/nodes_images.py, comfy_extras/nodes_textgen.py, and many model-family files such as comfy_extras/nodes_flux.py and comfy_extras/nodes_wan.py. A smaller legacy set still exposes NODE_CLASS_MAPPINGS directly, such as comfy_extras/nodes_model_advanced.py, comfy_extras/nodes_model_patch.py, comfy_extras/nodes_model_merging.py, comfy_extras/nodes_video_model.py, and comfy_extras/nodes_hooks.py; nodes.py registers both styles and stamps loaded node classes with RELATIVE_PYTHON_MODULE.

The collection is organized by feature family rather than one monolithic package:

Because comfy_extras is broad, the most important behavior is how nodes bridge graph-level IO schemas to core runtime contracts. Media nodes must preserve tensor shapes (IMAGE is batch/H/W/C, masks are B/H/W, audio is {"waveform", "sample_rate"}, video is Input.Video). Conditioning/model-specific nodes must write keys that the target model code consumes later, such as Flux guidance fields in comfy_extras/nodes_flux.py, Wan concat_latent_image/concat_mask fields in comfy_extras/nodes_wan.py, or SAM3 text prompt metadata in comfy_extras/nodes_sam3.py. Model patching nodes must clone models before mutating sampling objects or installing callbacks, as shown in comfy_extras/nodes_model_advanced.py and comfy_extras/nodes_model_patch.py.

Routing / covers

Route changes here when they touch comfy_extras/**: built-in extra node registration patterns, optional media nodes, model-specific conditioning/latent nodes, extra sampler/model patch/merge/training nodes, 3D/mesh/splat nodes, detection/pose/SAM/MediaPipe flows, and workflow utility nodes under this directory. Startup list changes in nodes.py:init_builtin_extra_nodes() affect this area because that list is the loader entry point for comfy_extras, but the source ownership for the registered modules remains comfy_extras/**.

Coupling

Risks

  • nodes.py:init_builtin_extra_nodes() is an explicit hand-maintained import list for more than a hundred comfy_extras/nodes_*.py files. If a new file is created under comfy_extras/** but not added there, users see no node even though local tests can import the file directly.
  • comfy_extras/nodes_train.py mutates global model-management state (comfy.model_management.training_fp8_bwd and comfy.model_management.in_training) and installs/ejects gradient-checkpoint or bypass hooks. If an exception path misses cleanup, later inference can run with training/offload behavior still active; the node uses finally blocks around the training loop for this reason.
  • comfy_extras/nodes_video.py depends on PyAV/container codec behavior and has recent churn around bit depth, chroma subsampling, ProRes, and preview caching. If SaveVideo, CreateVideo, or Input.Video.save_to() options drift, workflows may silently re-encode with the wrong format, lose HDR/chroma settings, or produce previews that do not match final output.
  • comfy_extras/nodes_save_3d.py and comfy_extras/nodes_mesh_io.py enforce strict vertex/face/UV/normal length invariants. If a mesh-processing node emits padded data without preserving vertex_counts/face_counts, GLB export can include padding geometry or raise out-of-range face errors.
  • comfy_extras/nodes_loop.py rewrites the prompt graph by copying every node in the loop body and remapping links. If node metadata such as _loop_body, _loop_end, or override display IDs changes in the execution system, nested loops or cached iteration reuse can execute the wrong copied node or lose progress reporting.