HyperFlow Loader:
HyperFlowLoader loads a HyperFlow diffusion transformer so you can use it in a ComfyUI generation workflow. It supports two checkpoint formats: GGUF, which requires the ComfyUI-GGUF extension, and HyperFlow INT8 convrot safetensors, which use ComfyUI’s INT8 processing capabilities. These formats store model weights—the learned values that guide generation—in compact representations. The loader also restores the HyperFlow-specific model structures and sampling schedule needed to use the checkpoint correctly, rather than treating it as an ordinary diffusion model. For GGUF checkpoints, it provides control over whether weights that cannot fit in GPU memory remain available from disk or are copied into system RAM. For supported safetensors checkpoints, it uses ComfyUI’s own model-loading and memory-management mechanisms.
HyperFlow Loader Input Parameters:
unet_name
Required dropdown selection identifying the HyperFlow checkpoint to load. The available options are assembled from the GGUF and safetensors file-discovery helpers, combined without duplicates, and sorted by name; the exact choices therefore depend on the compatible files available in your installation. The intended model location is ComfyUI’s diffusion_models folder, and GGUF discovery also checks registered unet_gguf and unet locations. Select either a HyperFlow GGUF checkpoint or a supported HyperFlow INT8 convrot safetensors checkpoint; a file having the correct extension alone does not guarantee compatibility. A filename ending in .gguf uses the GGUF loading route, while other listed checkpoints use the safetensors route. This choice determines the model being loaded, its storage format, and its loading requirements. No explicit default filename is declared, and minimum and maximum values do not apply.
weights_in
Optional dropdown controlling where GGUF model weights that do not fit on the GPU are kept. The available options are auto, ram, and disk, with auto as the default; numerical minimum and maximum values do not apply. Choose ram to copy those weights into system memory, or disk to keep them in the memory-mapped checkpoint file and stream them as needed, which can help when system RAM is limited. The documented automatic behavior selects disk storage when --fast-disk is enabled or a fast NVMe drive is detected. This parameter affects memory use and data-transfer performance rather than selecting a different model or sampling schedule. It applies only to GGUF checkpoints and has no effect on safetensors loading. If the installed ComfyUI-GGUF backend does not support keeping weights in the file, the loader issues a warning and falls back to RAM.
HyperFlow Loader Output Parameters:
model
A MODEL object containing the loaded HyperFlow transformer, wrapped for use with ComfyUI’s model-management system. This is the generation model, not a finished image, video, latent, or separately exposed sampling schedule. The loader configures the checkpoint’s factorized model components and restores its HyperFlow-specific endpoint-time components when present; supported safetensors checkpoints must contain these required endpoint tensors. It also attaches a sampling schedule to the underlying model, using the checkpoint’s stored schedule when available or a default schedule for GGUF checkpoints without one. You can connect this output to compatible sampling components and to HyperFlow Sigmas, which reads or constructs the appropriate schedule for sampling. The output does not include a text encoder or VAE, so any additional components required by your workflow must be supplied separately.
HyperFlow Loader Usage Tips:
- Place a compatible HyperFlow checkpoint in ComfyUI’s
models/diffusion_modelsdirectory or a configured equivalent. For GGUF files, registeredunet_ggufandunetlocations are also searched. If the filename is missing from the dropdown after adding it, refresh ComfyUI’s model lists or restart ComfyUI. - Start with
weights_inset toautofor GGUF models. If system RAM is limited and the checkpoint is on fast storage, trydiskexplicitly; this keeps weights that cannot fit on the GPU backed by the file rather than copying them into RAM. - Try
weights_inset toramwhen you have sufficient system RAM and disk streaming is a performance bottleneck. Compare loading and generation behavior on your own hardware; neither storage mode is universally faster. - Install a compatible ComfyUI-GGUF extension before selecting a GGUF checkpoint. Check the console for the loader’s disk-versus-RAM message to confirm which storage mode was actually used.
- For HyperFlow INT8 convrot safetensors, use a ComfyUI installation that supports the required INT8 kernels. Changing
weights_inwill not alter this loading route or solve its compatibility problems. - Connect
modelto HyperFlow Sigmas when building the sampling workflow. The provided guidance recommends SamplerCustom with theeulersampler and CFG set to1; choose4steps for speed,6for a balance of speed and quality, or8to favor quality. - Read the console after loading. HyperFlow reports useful details such as the number of factorized blocks and the sampling-schedule length; the GGUF route also reports whether transformer weights are kept on disk or in RAM.
HyperFlow Loader Common Errors and Solutions:
HyperFlow: this ComfyUI-GGUF cannot keep weights in the file; falling back to ram
- Explanation: This is a warning, not necessarily a loading failure. Disk-backed storage was selected, but the installed ComfyUI-GGUF backend does not support it, so the loader switches to RAM.
- Solution: Continue with RAM if your machine has enough available memory. If you need disk-backed storage, install a ComfyUI-GGUF version that supports it and restart ComfyUI; selecting
diskcannot override a backend limitation.
[checkpoint path] has HyperFlow metadata but no step-endpoint tensors
- Explanation: This error is raised by the safetensors loader when the checkpoint lacks one or more required HyperFlow components: the endpoint gate, sampling schedule, or endpoint tensors. The file may be incomplete or incompatible with this loader.
- Solution: Use a complete HyperFlow INT8 convrot safetensors checkpoint intended for this extension. Verify the download and replace the checkpoint if necessary; renaming an ordinary safetensors file will not add the missing components.
GGUF backend unavailable or ComfyUI-GGUF import failure
- Explanation: The GGUF loading route requires ComfyUI-GGUF. If that extension is missing or cannot load, HyperFlowLoader cannot read and configure the checkpoint. The exact error wording depends on the backend; it is not specified in the supplied code.
- Solution: Install or repair ComfyUI-GGUF in the same ComfyUI installation, restart ComfyUI, and inspect startup logs for extension-loading failures. Alternatively, use a supported HyperFlow INT8 convrot safetensors checkpoint.
Checkpoint not listed in unet_name
- Explanation: This is a file-discovery issue rather than a specific exception message. The dropdown contains only files returned by the GGUF and safetensors discovery helpers, so files in unregistered locations or files not recognized by those helpers may be absent.
- Solution: Put the checkpoint in
models/diffusion_modelsor a configured model location, confirm that the file is fully downloaded, and refresh the model list or restart ComfyUI. For GGUF checkpoints, confirm that the filename ends in.gguf.
File not found or checkpoint cannot be opened
- Explanation: A selected checkpoint may have been moved, renamed, deleted, or made inaccessible since the model list was populated. The exact filesystem error depends on the underlying loading function.
- Solution: Confirm that the checkpoint still exists in the configured model folder and that ComfyUI can read it. Refresh the model list and select the current filename; if using disk-backed GGUF weights, keep the checkpoint storage accessible during use.
Unsupported or incompatible checkpoint
- Explanation: This loader is designed for HyperFlow GGUF and HyperFlow INT8 convrot safetensors checkpoints, not arbitrary models with those extensions. Incompatible architecture, metadata, or tensor layouts may cause validation or model-loading errors; the supplied code does not define a single message for all such failures.
- Solution: Verify that the checkpoint is explicitly intended for HyperFlow and this loading method. Use compatible ComfyUI and extension versions, and check the first detailed console error before changing unrelated workflow settings.
INT8 kernel or operation compatibility error
- Explanation: The supported safetensors route relies on ComfyUI’s INT8 kernels. An installation that lacks the required support may fail during model loading or execution, with wording determined by the underlying operation.
- Solution: Check that your ComfyUI version and runtime support the checkpoint’s INT8 requirements. Update compatible components as needed, or use a supported HyperFlow GGUF checkpoint with ComfyUI-GGUF. Changing
weights_indoes not change safetensors execution.
Out of memory during loading or sampling
- Explanation: Model loading or generation can exceed available GPU memory or system RAM. GGUF disk-backed weights can reduce RAM pressure from weights that do not fit on the GPU, but do not eliminate memory needed for computation and other workflow components.
- Solution: Close other memory-heavy applications and reduce the generation workload where appropriate. For GGUF RAM pressure, try
weights_inset todiskand verify that no fallback warning appears. For safetensors, rely on ComfyUI’s memory-management settings rather thanweights_in, which is ignored for that format.
