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 > HunyuanImage-3.0 Looped Diffusion

ComfyUI Node: HunyuanImage-3.0 Looped Diffusion

Class Name

HunyuanImage3Looping

Category
model/patch/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

HunyuanImage-3.0 Looped Diffusion Description

Runs selected HunyuanImage-3.0 transformer layers twice per sampling step to improve generation.

HunyuanImage-3.0 Looped Diffusion:

HunyuanImage3Looping, displayed as “HunyuanImage-3.0 Looped Diffusion,” modifies how HunyuanImage-3.0 processes an image during generation by running a selected group of transformer layers twice per sampling step. Transformer layers are stages of the model’s internal processing; repeating a group gives the model another pass through that processing without retraining it. This training-free approach, described as Looped-DiT, can help with demanding image-generation tasks such as dense text, closer adherence to your prompt, or counting objects. Repeating earlier layers is intended to help dense text and prompt adherence, while repeating middle layers can help counting but may also cause subjects to disappear. The node changes the model’s processing behavior rather than increasing the number of sampling steps or generating an image itself. Its documented trade-off is approximately 15–27% more time per sampling step, and improvements depend on your prompt and the selected repetition strategy.

HunyuanImage-3.0 Looped Diffusion Input Parameters:

model

The required MODEL connection supplies the model whose processing you want to modify. Use a compatible HunyuanImage-3.0 model, because the repetition setting is read by the HunyuanImage-3.0 implementation shown in the provided code. The node clones the supplied model wrapper and adds the looping configuration to that clone, leaving the incoming model’s configuration unchanged. This lets you keep an unmodified branch for comparison while using the modified branch for generation. The node does not load model weights, retrain the model, or directly change your prompt. There is no numeric minimum, maximum, or default value for this connection; you must supply a MODEL from your workflow.

preset

The required COMBO selection determines which group of layers is repeated and how strongly the repeated processing updates the model’s internal state. The default is early x2. The supplied preset definitions are early x2, which repeats layers 4–9 with a full-strength update of 1.0; mid x2, which repeats layers 11–20 with a full-strength update of 1.0; and mid x2 half, which repeats layers 11–20 with an update scale of 0.5. These layer numbers follow the implementation’s indexing, and the end of each configured span is exclusive. Choose early x2 when testing dense text or prompt adherence, and consider the middle-layer presets when testing object counts, keeping in mind that they may drop subjects. In mid x2 half, each repeated layer blends its incoming internal state and its newly computed result equally, making the repeated updates less strong than in mid x2. “Half” does not mean half the repeated layers, half the sampling steps, or half the processing time. This is a fixed-choice setting, so numeric minimum and maximum values do not apply.

HunyuanImage-3.0 Looped Diffusion Output Parameters:

MODEL

The MODEL output is the cloned model configured to use the selected layer-repetition preset. Internally, the node stores this configuration under hy3_loop in the model’s transformer options, which the compatible HunyuanImage-3.0 implementation uses during processing. Connect this output to the model path used by your sampler so that subsequent generation uses the modified behavior. It is still a MODEL connection, not an image, conditioning result, or collection of newly trained weights. Its importance is that it carries the looping behavior forward in your workflow while allowing the original incoming model configuration to remain available separately.

HunyuanImage-3.0 Looped Diffusion Usage Tips:

  • Start with early x2, the default preset, when your main concern is dense text or following a detailed prompt. Treat it as a targeted experiment rather than a guaranteed improvement.
  • Try mid x2 for prompts where the number of objects matters. Check both the count and the presence of every requested subject, because the node description explicitly warns that middle-layer repetition may drop subjects.
  • Compare mid x2 half against mid x2 if full-strength middle-layer repetition changes the composition too much. It reduces the strength of each repeated update, but it does not eliminate the extra layer executions or guarantee that missing subjects will return.
  • Keep your prompt, seed, sampler settings, resolution, and other model modifications unchanged when comparing presets. This makes it easier to identify what the looping setting actually changes.
  • Route the node’s MODEL output into your sampling path. If the sampler still receives the original model, the looping configuration on the cloned branch will not affect that generation.
  • Budget for the documented increase of approximately 15–27% in time per sampling step. Test a small batch before committing to a long generation run, since actual timing depends on your setup.
  • Use separate branches for preset comparisons. Applying this node again to the same model branch replaces its existing hy3_loop setting rather than combining multiple looping presets.

HunyuanImage-3.0 Looped Diffusion Common Errors and Solutions:

Missing required input: model

  • Explanation: This is a descriptive validation issue rather than an exact error string supplied by the node. The node requires a MODEL connection and cannot configure looping without one.
  • Solution: Connect a compatible HunyuanImage-3.0 MODEL output to model, then confirm that the upstream model-loading node completes successfully.

Invalid preset selection or KeyError

  • Explanation: The node looks up the selected value directly in LOOP_PRESETS. If an edited workflow or programmatic call supplies an unknown preset name, Python can raise a KeyError containing that value. ComfyUI may instead reject the selection during input validation.
  • Solution: Select early x2, mid x2, or mid x2 half from the dropdown. If an older workflow contains an unavailable value, reselect a valid preset or recreate the node.

Looping has no visible effect

  • Explanation: This is a troubleshooting symptom, not a defined error message. The sampler may still be connected to the original model, or the model implementation may not read the HunyuanImage-3.0-specific hy3_loop setting. Even with correct wiring, a particular prompt may not show an obvious visual improvement.
  • Solution: Confirm that your sampling path receives this node’s MODEL output and that you are using the compatible HunyuanImage-3.0 implementation. Compare against an unmodified branch using the same seed and settings, and test prompts involving the intended targets, such as dense text or object counts.

Generation takes longer after enabling looping

  • Explanation: This is expected behavior rather than an error: the selected transformer layers are executed again. The documented overhead is approximately 15–27% per sampling step, although your actual timing may differ.
  • Solution: Compare timing with the same workflow bypassing this node to establish the added cost. Use looping where its visual benefit justifies the extra time, and do not expect mid x2 half to halve that overhead, because it still executes the repeated layers.

Subjects disappear or the composition becomes less faithful

  • Explanation: This is a documented possible side effect of the middle-layer presets, not a software exception. Improvements in counting can come with the loss of requested subjects, and repeating layers does not guarantee better results for every image.
  • Solution: Compare mid x2 half with mid x2 to test gentler repeated updates, switch to early x2 when prompt adherence is the priority, or bypass looping if the unmodified model preserves your composition better. Check several seeds before choosing a preset for a larger batch.

HunyuanImage-3.0 Looped Diffusion 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.

HunyuanImage-3.0 Looped Diffusion