Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-HunyuanImage3 > Load HunyuanImage 3.0 Model

ComfyUI Node: Load HunyuanImage 3.0 Model

Class Name

HunyuanImage3ModelLoader

Category
model/loaders/hunyuan image 3
Author
PedroMarinhoDev (Account age: 43days)
Extension
ComfyUI-HunyuanImage3
Latest Updated
2026-11-03
Github Stars
0.04K

How to Install ComfyUI-HunyuanImage3

Install this extension via the ComfyUI Manager by searching for ComfyUI-HunyuanImage3
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-HunyuanImage3 in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

Load HunyuanImage 3.0 Model Description

Loads HunyuanImage 3.0 checkpoints in ComfyUI and automatically detects model variants.

Load HunyuanImage 3.0 Model:

HunyuanImage3ModelLoader, displayed in ComfyUI as “Load HunyuanImage 3.0 Model,” prepares a HunyuanImage 3.0 checkpoint for use in an image-generation workflow. A checkpoint contains the learned weights that define a model’s capabilities. This node supports the Instruct-Distil, Instruct, and Base variants and automatically identifies the variant by examining those weights, rather than requiring you to select a model type manually. Its purpose is to make loading these models straightforward while handling their integration with ComfyUI’s model system. The node is described as supporting any HunyuanImage 3.0 checkpoint format, but the checkpoint should be prepared for ComfyUI and compatible with the installed extension. It loads the image-generation model; it does not generate an image or configure an entire workflow by itself.

Load HunyuanImage 3.0 Model Input Parameters:

model

A required COMBO selection that chooses the HunyuanImage 3.0 checkpoint to load. The available options come from ComfyUI’s registered diffusion_models file list, normally populated by files in ComfyUI/models/diffusion_models and any additional configured locations for that category. Choose a checkpoint converted for ComfyUI; the loader determines whether it is Instruct-Distil, Instruct, or Base from its weights. This selection determines which model is prepared for your workflow, so changing it changes the underlying model used by subsequent generation steps. When executed, the node resolves the selected filename to a full file path and loads that checkpoint. Options are installation-dependent rather than a fixed list. The default is selected by _default_checkpoint(); its implementation is not provided, so a specific default filename cannot be established from the supplied code. Minimum and maximum values do not apply because this is a file-selection dropdown, not a numeric setting.

Load HunyuanImage 3.0 Model Output Parameters:

model

A MODEL connection containing the loaded HunyuanImage 3.0 model wrapped for use within ComfyUI’s model-management system. The node returns the model patcher produced by the HunyuanImage 3.0 loading routine, which allows compatible downstream nodes to work with the loaded model. For your workflow, this is the prepared image-generation model that subsequent processing or sampling stages can use. It is not an image, a text prompt, or a report of the detected variant, and there is no separate output identifying whether the checkpoint is Instruct-Distil, Instruct, or Base. Connect it to an appropriate MODEL input in a workflow designed for HunyuanImage 3.0.

Load HunyuanImage 3.0 Model Usage Tips:

  • Place your ComfyUI-compatible HunyuanImage 3.0 checkpoint in ComfyUI/models/diffusion_models or another configured diffusion_models location. Refresh the model list or restart ComfyUI if a newly added checkpoint does not appear.
  • Select the checkpoint you intend to use without looking for a separate Base, Instruct, or Instruct-Distil setting. Variant detection is automatic and based on the checkpoint’s weights; renaming a file does not change its model type.
  • Start with an example workflow supplied for your checkpoint or the HunyuanImage 3.0 extension. This loader prepares only the model, so other required generation components must be provided elsewhere in the workflow.
  • When switching between model variants, check the checkpoint’s recommended downstream generation settings. Automatic identification during loading does not mean this node sets every sampling or workflow option for you.
  • This node exposes only checkpoint selection. It has no controls for precision, device placement, memory limits, sampling steps, or image resolution, so any supported adjustments to those settings must be made elsewhere.
  • If memory is limited, close other GPU-intensive applications before loading. If your extension offers multiple compatible checkpoint formats, consult its documentation for their memory requirements rather than assuming every format has the same resource needs.

Load HunyuanImage 3.0 Model Common Errors and Solutions:

Checkpoint missing from the model dropdown

  • Explanation: The dropdown lists files registered under ComfyUI’s diffusion_models category. A checkpoint stored elsewhere, added after the list was populated, or not recognized by ComfyUI’s file listing may be absent. This is a selection issue rather than a confirmed loader exception.
  • Solution: Confirm that the checkpoint is in ComfyUI/models/diffusion_models or a correctly configured additional location. Check that the download is complete, then refresh the model list or restart ComfyUI.

Selected checkpoint cannot be found

  • Explanation: Execution requires the selected filename to resolve to an existing file. If the file was moved, renamed, deleted, or stored on a disconnected drive, path resolution can fail. The supplied code uses get_full_path_or_raise, but does not show the exact resulting error text.
  • Solution: Restore the file or select its current entry from the dropdown. If you use an external drive or network location, reconnect it and verify that ComfyUI can access the checkpoint.

Checkpoint is incompatible or model type cannot be detected

  • Explanation: The loader expects HunyuanImage 3.0 weights and identifies the variant from their contents. A checkpoint for another model family, an incompatible conversion, or incomplete weights may prevent identification or loading. The supplied excerpts do not establish an exact error message for this case.
  • Solution: Verify that you downloaded a HunyuanImage 3.0 checkpoint prepared for ComfyUI. Follow the extension’s checkpoint preparation instructions and confirm that your installed extension version supports that release.

Missing keys, unexpected keys, or tensor size mismatch

  • Explanation: These are possible model-loading diagnostics when a checkpoint’s stored weights do not match the architecture expected by the installed loader. They may indicate an incompatible conversion, a different model architecture, or a version mismatch. Not every warning about keys is necessarily fatal; the surrounding log determines whether loading failed.
  • Solution: Check that the checkpoint and extension versions are compatible. Update the extension if required by the checkpoint documentation, use a documented conversion, and review the first relevant error in the ComfyUI console rather than only the final failure notice.

Checkpoint cannot be read or deserialized

  • Explanation: Loading may fail if the downloaded file is incomplete, damaged, unreadable, or not actually a supported checkpoint file. Exact file-reading errors depend on the underlying loader and are not included in the supplied source.
  • Solution: Compare the file size or checksum with the download source when available. Download the checkpoint again if necessary, confirm that the file is fully downloaded rather than a placeholder, and check that the account running ComfyUI has read access.

Out of memory during loading

  • Explanation: Preparing a large model can exceed available system RAM or GPU memory, depending on the checkpoint and ComfyUI’s loading behavior. A message such as “CUDA out of memory” is a possible runtime error, not a custom message shown in this node’s source.
  • Solution: Close other memory-intensive applications and unload unused models before trying again. Check the checkpoint’s hardware requirements and the extension’s documented memory-saving options. This node has no memory or precision controls, so any supported changes must be configured elsewhere.

Load HunyuanImage 3.0 Model Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-HunyuanImage3
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

Load HunyuanImage 3.0 Model