HyperFlow GGUF Loader:
HyperFlowGGUFLoader loads a HyperFlow diffusion transformer stored in GGUF format and prepares it for use in ComfyUI. GGUF can store model weights—the numerical data that defines the model—in a compressed, quantized form, helping reduce their storage and memory requirements compared with full-precision versions. This node uses ComfyUI-GGUF’s operations to interpret those weights as needed during computation, while applying HyperFlow-specific handling for factorized model blocks and optional two-time components when present in the checkpoint. It also preserves the checkpoint’s sampling schedule, or supplies the standard HyperFlow schedule if none is stored. Its memory-management support can keep weights that do not fit on the GPU either in system RAM or backed by the model file, making it useful for running compatible HyperFlow checkpoints on machines with different memory capacities. The ComfyUI-GGUF custom-node package is required.
HyperFlow GGUF Loader Input Parameters:
unet_name
A required COMBO[STRING] selection identifying the HyperFlow GGUF checkpoint to load. The available options are generated from filenames ending in .gguf in ComfyUI’s registered unet_gguf, diffusion_models, and unet model folders; duplicate names are removed and the list is sorted. Choose a checkpoint intended for HyperFlow, because appearing in the list only confirms that a file has the expected extension, not that its internal model structure is compatible. Your selection determines which model weights and checkpoint-specific components are loaded, including any embedded sampling schedule. There is no explicitly declared default filename, and numeric minimum and maximum values do not apply. If the list is empty, check that a compatible checkpoint is installed in one of the registered model locations and refresh or restart ComfyUI.
weights_in
An optional COMBO[STRING] setting that controls where GGUF transformer weights remain when they are not held on the GPU. The options are auto, ram, and disk, with auto as the default; numeric minimum and maximum values do not apply. With ram, these weights are copied into system RAM, which can avoid repeated storage access but requires enough available RAM. With disk, weights that do not fit on the GPU stay backed by the memory-mapped model file and stream from storage as needed, making this useful when system RAM is limited; performance then depends on storage speed. The documented behavior of auto is to use disk-backed weights with --fast-disk or a fast NVMe drive, leaving the storage choice to the loader’s detection logic. This setting changes weight placement rather than choosing a different checkpoint or sampling schedule. Disk-backed operation also requires a compatible ComfyUI-GGUF implementation; if that support is unavailable, the loader logs a warning and falls back to RAM.
HyperFlow GGUF Loader Output Parameters:
model
A MODEL object containing the loaded HyperFlow diffusion transformer, prepared for ComfyUI’s model-processing and sampling workflow. This is a working model object rather than a generated image, video, or raw collection of weights. It includes the GGUF-aware execution support and installed HyperFlow-specific model components, and its diffusion model carries a sampling schedule taken from the checkpoint or supplied by the loader’s default schedule. The returned model also uses the selected or automatically determined weight-storage strategy, subject to the RAM fallback when disk-backed operation is unsupported. You can connect it to compatible downstream nodes that accept MODEL, including HyperFlow Sigmas to obtain the appropriate SIGMAS schedule. It does not provide text encoders, a VAE, conditioning, or latent data, so those parts must be supplied separately by your workflow.
HyperFlow GGUF Loader Usage Tips:
- Install and enable
city96/ComfyUI-GGUFbefore using this node, then restart ComfyUI. The loader looks for that package’s registeredUnetLoaderGGUFnode to locate its GGUF backend. - Place your compatible HyperFlow
.ggufcheckpoint in a registered model location, such asComfyUI/models/diffusion_models, and refresh the model list or restart ComfyUI. Checkpoint compatibility matters: this is not a general-purpose loader for every GGUF architecture. - Start with
weights_inset toauto. Check the console messageHyperFlow: transformer weights in diskorHyperFlow: transformer weights in ramto confirm the actual storage choice; the complete log line also reports your requested setting. - Try
diskif system RAM is your main constraint, preferably with the checkpoint on fast local NVMe storage. Disk backing reduces the need to copy non-GPU weights into RAM, but it does not remove all RAM or GPU-memory requirements. - Try
ramif you have enough free system RAM and storage access is slowing execution. Compare performance on your own machine rather than assuming that one storage mode is always faster. - Connect the model to HyperFlow Sigmas and use its SIGMAS output with SamplerCustom. The provided companion node recommends
eulersampling with CFG set to1and supports 4 steps for speed, 6 steps by default for balance, or 8 steps for quality. - Use HyperFlow Loader instead if your checkpoint is an INT8 convrot
.safetensorsfile. HyperFlowGGUFLoader lists and loads only.ggufcheckpoints.
HyperFlow GGUF Loader Common Errors and Solutions:
HyperFlow GGUF loading needs the ComfyUI-GGUF custom node (city96/ComfyUI-GGUF).
- Explanation: This is the explicit error raised when the loader cannot find the registered
UnetLoaderGGUFnode. ComfyUI-GGUF may be missing, disabled, or unable to import successfully. - Solution: Install or enable
city96/ComfyUI-GGUFand restart ComfyUI. If it is already installed, inspect the startup console for import failures and resolve its missing dependencies or compatibility issues.
HyperFlow: this ComfyUI-GGUF cannot keep weights in the file; falling back to ram
- Explanation: This is a warning rather than a loading failure. Disk-backed storage was selected, but the installed ComfyUI-GGUF implementation does not support the required behavior, so the loader switches to RAM.
- Solution: Allow loading to continue if you have enough system RAM. If you need disk-backed loading, check for compatible updates to ComfyUI-GGUF and ComfyUI-HyperFlow-Flash, restart ComfyUI, and confirm that the console now reports weights in disk.
No checkpoints appear in unet_name
- Explanation: This is an interface symptom rather than a specific exception. The node found no filenames ending in
.ggufin its registeredunet_gguf,diffusion_models, orunetlocations. - Solution: Verify that your checkpoint has finished downloading, ends in
.gguf, and is stored in a registered model folder. Refresh the interface or restart ComfyUI after moving the file. A.safetensorscheckpoint will not appear in this node.
Selected checkpoint is unavailable or cannot be opened
- Explanation: The precise error depends on file lookup and operating-system handling. A workflow may reference a checkpoint that was moved, renamed, deleted, or made inaccessible after it was selected.
- Solution: Select an existing checkpoint again, verify its location, and ensure ComfyUI has permission to read it. If the model is on an external or network drive, confirm that the drive is connected and available before running the workflow.
GGUF parsing or unsupported model errors during loading
- Explanation: The exact message depends on the GGUF reader and model-loading stage. Possible causes include an incomplete or damaged file, an incompatible GGUF architecture, or checkpoint contents that do not match the HyperFlow structure expected by this loader. A
.ggufextension alone does not establish compatibility. - Solution: Confirm that the checkpoint is specifically intended for HyperFlow and supported by your installed extension versions. Check the download’s integrity if a checksum is provided, and download the file again if it may be incomplete. Use the appropriate architecture-specific loader for unrelated GGUF models.
Out of memory during loading or sampling
- Explanation: The exact wording depends on whether system RAM or GPU memory is exhausted. Quantized weights and disk-backed storage can reduce some memory requirements, but model execution still needs memory for active weights, intermediate calculations, and other workflow components.
- Solution: If system RAM is exhausted, try
weights_inset todiskand confirm that the loader does not fall back to RAM. If GPU memory is exhausted during sampling, reduce workload settings such as resolution, frame count, or batch size where your workflow supports them, and close other GPU-heavy applications. Disk-backed loading is not a guarantee against GPU-memory errors.
