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:
- Media IO and editing live in files such as comfy_extras/nodes_images.py, comfy_extras/nodes_video.py, comfy_extras/nodes_audio.py, comfy_extras/nodes_post_processing.py, comfy_extras/nodes_mask.py, comfy_extras/nodes_morphology.py, comfy_extras/nodes_compositor.py, and comfy_extras/compositor_blend.py. They convert between Comfy tensor conventions and file/UI formats, using
folder_pathsfor input/output locations,PromptServer/UI helpers for previews, PyAV for video containers, PIL/OpenEXR-style encoders for images, andcomfy.audiofor waveform processing. comfy_extras/nodes_video.py is the newer typed video flow:LoadVideowraps input files asInputImpl.VideoFromFile,CreateVideobuilds aVideoFromComponentsobject from image batches plus optional audio, transform nodes callas_trimmed()/as_cropped(), andSaveVideodelegates encoding to theInput.Videoobject with prompt metadata when enabled. - Model sampling, patching, and training live in comfy_extras/nodes_custom_sampler.py, comfy_extras/nodes_advanced_samplers.py, comfy_extras/nodes_model_advanced.py, comfy_extras/nodes_model_patch.py, comfy_extras/nodes_model_merging.py, comfy_extras/nodes_model_merging_model_specific.py, comfy_extras/nodes_torch_compile.py, comfy_extras/nodes_sparse_attention.py, comfy_extras/nodes_multigpu.py, and comfy_extras/nodes_train.py. These nodes are thin graph-facing adapters over core
comfy.samplers,comfy.model_sampling,comfy.model_patcher,comfy.patcher_extension,comfy.sd, andcomfy.model_managementAPIs. They create sigma schedules and sampler objects, clone models before adding object patches, install sampler/post-CFG callbacks, load patch weights from model folders, merge model/CLIP/VAE weights, or temporarily switch the model manager into training mode for LoRA training. - Model-specific conditioning and latent-shaping nodes are split into files named for the architecture or product line, including comfy_extras/nodes_flux.py, comfy_extras/nodes_sd3.py, comfy_extras/nodes_stable_cascade.py, comfy_extras/nodes_wan.py, comfy_extras/nodes_wanmove.py, comfy_extras/nodes_wandancer.py, comfy_extras/nodes_hunyuan.py, comfy_extras/nodes_hunyuan3d.py, comfy_extras/nodes_cosmos.py, comfy_extras/nodes_lumina2.py, comfy_extras/nodes_mochi.py, comfy_extras/nodes_qwen.py, comfy_extras/nodes_ming.py, comfy_extras/nodes_mage.py, comfy_extras/nodes_minimax_h3.py, comfy_extras/nodes_yue2.py, comfy_extras/nodes_zimage.py, comfy_extras/nodes_seedvr.py, and other adjacent model families. These nodes usually write agreed metadata into conditioning dictionaries with
node_helpers.conditioning_set_values, allocate correctly shaped zero latents oncomfy.model_management.intermediate_device(), run VAE encode/decode for reference media, or tune scheduler/model-sampling parameters expected by the corresponding corecomfy.ldm.*implementation. - Detection, segmentation, tracking, and 3D/body flows live in comfy_extras/nodes_rtdetr.py, comfy_extras/nodes_sam3.py, comfy_extras/nodes_sam3d_body.py, comfy_extras/nodes_mediapipe.py, comfy_extras/nodes_depth_anything_3.py, comfy_extras/nodes_moge.py, comfy_extras/nodes_bg_removal.py, plus helper packages under
comfy_extras/mediapipe/,comfy_extras/pose/, andcomfy_extras/sam3d_body/. These nodes load detection weights fromfolder_pathsmodel categories, callcomfy.model_management.load_model_gpu()before inference, and exchange structured bounding boxes, masks, custom landmark/track data, and pose/mesh payloads. A common flow is object boxes from comfy_extras/nodes_rtdetr.py or masks/tracks from comfy_extras/nodes_sam3.py feeding SAM 3D Body prediction and export nodes in comfy_extras/nodes_sam3d_body.py. - 3D assets, meshes, splats, camera utilities, and generation helpers live in comfy_extras/nodes_load_3d.py, comfy_extras/nodes_save_3d.py, comfy_extras/nodes_mesh_io.py, comfy_extras/nodes_mesh_postprocess.py, comfy_extras/nodes_gaussian_splat.py, comfy_extras/nodes_camera.py, comfy_extras/nodes_camera_angle.py, comfy_extras/nodes_trellis2.py, comfy_extras/nodes_triposplat.py, and comfy_extras/nodes_stable3d.py. The shared mesh contract is
Types.MESH: nodes_save_3d.py packs variable-sized mesh batches by padding tensors while carryingvertex_counts/face_counts, writes GLB data directly, and creates preview/save UI entries; nodes_mesh_io.py reads GLB/GLTF/OBJ/STL throughcomfy_extras/mesh3d/fileio, merges primitives, and preserves the first material's texture factors where possible. - Workflow utility and data-shaping nodes live in comfy_extras/nodes_loop.py, comfy_extras/nodes_logic.py, comfy_extras/nodes_toolkit.py, comfy_extras/nodes_primitive.py, comfy_extras/nodes_string.py, comfy_extras/nodes_text.py, comfy_extras/nodes_number_convert.py, comfy_extras/nodes_math.py, comfy_extras/nodes_resolution.py, comfy_extras/nodes_dataset.py, comfy_extras/nodes_bounding_boxes.py, and comfy_extras/nodes_preview_any.py. nodes_loop.py is notable because it implements graph expansion with
comfy_execution.graph_utils.GraphBuilder:StartLoopcopies body nodes for each iteration, injectsLoopIteration/LoopProgress/LoopResultnodes, and carries optional loop values and list items across iterations rather than executing a Python loop inside one node.
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
- If a new comfy_extras/nodes_*.py module is added, also add it to the explicit
extras_fileslist innodes.py:init_builtin_extra_nodes(); otherwise the module can define a validcomfy_entrypoint()orNODE_CLASS_MAPPINGSand still never be imported at startup. - If changing registration style in any extra node file, verify
nodes.py:load_custom_node()still sees eitherNODE_CLASS_MAPPINGSor callablecomfy_entrypoint()returning aComfyExtension. Legacy files such as comfy_extras/nodes_hooks.py populate mappings dynamically, while V3 files such as comfy_extras/nodes_video.py rely onget_node_list()and schemanode_ids. - If changing media tensor conventions, check all cross-media helpers that assume shape and metadata contracts: comfy_extras/nodes_images.py saves and previews image batches, comfy_extras/nodes_video.py wraps videos as typed
Input.Video, comfy_extras/nodes_audio.py expects audio dicts with waveform/sample-rate keys, comfy_extras/nodes_mask.py composites BCHW latents and BHWC images, and comfy_extras/nodes_post_processing.py preserves alpha in several filters. - If changing conditioning metadata keys for a model family, update the matching core model/sampler consumer, not just the node schema. For example comfy_extras/nodes_wan.py writes
concat_latent_image,concat_mask,reference_latents, and CLIP-vision fields into conditioning; comfy_extras/nodes_flux.py writes Flux guidance/reference-latent fields; comfy_extras/nodes_audio.py writes Stable Audio timing keys. - If changing mesh representation, update both conversion directions: comfy_extras/nodes_save_3d.py writes
Types.MESHto GLB and slices padded variable batches withvertex_counts/face_counts, while comfy_extras/nodes_mesh_io.py reads external files into the sameTypes.MESHfields. Model-specific 3D nodes such as comfy_extras/nodes_hunyuan3d.py and comfy_extras/nodes_trellis2.py also rely onpack_variable_mesh_batch(). - If changing bounding-box payload shape, check all producers and consumers. comfy_extras/nodes_rtdetr.py returns per-frame lists of dicts with
x,y,width,height,label, andscore; comfy_extras/nodes_sam3.py, comfy_extras/nodes_sam3d_body.py, comfy_extras/nodes_compositor.py, and visualization nodes normalize several single-frame and per-frame variants. - If changing file access in dataset, media, 3D, or save nodes, preserve
folder_pathscontainment and annotated-path behavior. comfy_extras/nodes_dataset.py explicitly rejects paths escaping dataset/input roots, while comfy_extras/nodes_video.py, comfy_extras/nodes_load_3d.py, and comfy_extras/nodes_save_3d.py usefolder_pathsto locate input/output/temp assets for UI previews.
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 undercomfy_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_bwdandcomfy.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 usesfinallyblocks 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, orInput.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.