Low-memory ComfyUI nodes for HunyuanImage-3.0-Instruct BF16, focused on running the full checkpoint on systems that cannot keep the model entirely in GPU VRAM or physical RAM.

This project is an unofficial fork of EricRollei/Comfy_HunyuanImage3. For documentation and features of the original project, use the upstream repository.

What this fork adds

CUDA + CPU + SSD-backed BF16 loading with Accelerate disk offload.
Low-VRAM reserve handling for consumer GPUs.
Universal T2I / single-image I2I workflow for HunyuanImage-3.0-Instruct.
Live denoised diffusion preview.
Best-effort latent preserve mask for local I2I edits.
Optional final RGB preservation inside the source mask.
Aspect-preserving tiled refinement for larger output sizes.
Hover tooltips for the public workflow controls.

Tested low-memory configuration

The low-memory BF16 path has been tested with:

NVIDIA RTX 5070, 12 GB VRAM
64 GB system RAM
96 GB Windows pagefile
HunyuanImage-3.0-Instruct BF16 checkpoint
Transformers 4.57.6
Accelerate 1.14.0
SSD disk offload enabled

This mode is very slow because most model weights are streamed through CPU memory and SSD storage. It is intended for users who accept the performance tradeoff in exchange for running the full BF16 Instruct checkpoint on low-memory hardware.

Installation

Clone the repository into the ComfyUI custom-nodes directory:

cd C:\ComfyUI\ComfyUI\custom_nodes
git clone https://github.com/foxidermist/hunyuanimage3-low-memory.git

Install the repository requirements with the Python environment used by ComfyUI:

C:\ComfyUI\python_embeded\python.exe -m pip install -r C:\ComfyUI\ComfyUI\custom_nodes\hunyuanimage3-low-memory\requirements.txt

Restart ComfyUI after installation.

Model location

Place the complete HunyuanImage-3.0-Instruct repository in a directory visible to the loader. A typical location is:

ComfyUI/models/HunyuanImage-3.0-Instruct

An external model directory can also be registered through extra_model_paths.yaml.

Public workflow

The repository contains one supported workflow:

workflows/HunyuanImage3_Instruct_Universal_0.4.0.json

It covers T2I, single-image I2I, optional source preservation, live diffusion preview, and optional tiled refinement.

T2I

Leave image and preserve_mask disconnected in Hunyuan Instruct Generate / Edit.

I2I

Connect a single source image and describe the requested edit.

When primary_image_controls_size is enabled, the source aspect ratio is mapped to a native Hunyuan bucket and the final result is returned at the source dimensions.

Preserve mask

WHITE means preserve source content. BLACK remains editable.

Two preservation stages are available.

Latent preserve

latent_preserve_mask = true applies per-step source-latent locking under the white mask.

Recommended defaults:

preserve_mask_expand   = 0
preserve_mask_feather  = 8
preserve_mask_strength = 1.0

This is a best-effort inference technique, not model-native masked inpainting. It works best when the protected subject stays close to its original position and scale.

Final RGB preserve

final_pixel_preserve = true restores source RGB pixels after the final VAE decode.

Defaults:

final_pixel_expand  = 2
final_pixel_feather = 4

This preserves exact source color and detail at the original coordinates. It cannot track an object that the model moved or resized.

Diffusion preview

Enable diffusion_preview to display denoised x0 previews while sampling.

Intermediate preview VAE decodes bypass the final low-memory pre-VAE cleanup wrapper. The normal final VAE decode still performs the cleanup required by the low-memory path.

Preview performs extra VAE work, so increasing diffusion_preview_every can save substantial time with SSD offload.

Recommended BF16 low-memory loader settings

For a 12 GB GPU, start with:

use_disk_offload   = true
blocks_to_swap     = 0
cpu_memory_limit_gb = 32
vram_reserve_gb    = 8

On GPUs below 24 GiB, the loader clamps the effective inference reserve to 5 GiB.

Use a fast SSD for the offload directory and keep substantial free disk space available.

Tiled refinement

Hunyuan Instruct Tiled Refine enlarges the generated image and processes tiles sequentially.

Default settings:

scale_multiplier = ×4
tile_steps       = 4
max_tiles        = 0
refine_strength  = 0.25
feather          = 128
tiled_preview    = true

Tiled refinement does not receive or reapply the preserve mask. Use the native output when exact protected pixels are required.

Important limitations

Full BF16 SSD offload is dramatically slower than running the model in VRAM.
The full Instruct model uses CFG and has substantially higher inference-memory pressure than distilled variants.
Preserve masks are not native Hunyuan inpainting masks.
Large subject movement, pose changes, or scale changes can conflict with source preservation.
Tiled refinement is a separate second pass, not native single-pass high-resolution generation.

License

See LICENSE in this repository.