Hunyuan 3 Loader (Multi-GPU BF16)

"Hunyuan 3 Loader (Multi-GPU BF16)" splits the full-precision HunyuanImage-3.0 across multiple GPUs instead of forcing it onto one. Two 4090s, an 80B model, no quantization - that's the pitch. It's the option for people who have the cards but not one single 80GB+ GPU, and the README's own multi-GPU benchmark (2× RTX 4090, ~3.5s/step at 1MP) shows it's legitimately usable.

How it works

The loader spreads the transformer blocks over the GPUs it can see and designates one as primary - the card where inference actually runs. Controls:

• primary_gpu - which GPU does the sampling (default 0).
• reserve_memory_gb - VRAM left free on the primary for inference, default 12GB. This is the "don't make the primary card so full it can't generate" knob.
• exclude_gpus - a string listing GPUs to skip (e.g. "1" if card 1 is busy driving a display or another model). Useful when ComfyUI sees a GPU you don't want to use.
• info - a read-only string that reports the detected CUDA state, which makes it a quick sanity check that both cards are visible. If it still says "No CUDA GPUs detected," something upstream is hiding your GPUs.

Output is a single HUNYUAN_MODEL. The weights are the full BF16 release:

cd ComfyUI/models
huggingface-cli download tencent/HunyuanImage-3.0 --local-dir HunyuanImage-3

The gotchas

Multi-GPU Hunyuan was a bug farm for a while, and the README's changelog shows the scar tissue: issue #15 was a device mismatch where freqs_cis / image_pos_id ended up on the wrong GPU during block-swap forwards, fixed by explicit .to(device) calls. If you hit a "tensors on different devices" error, it's worth checking you're on the latest version of the pack.

The other classic trap: CUDA_VISIBLE_DEVICES. If ComfyUI only sees one GPU, check that environment variable - the README's first troubleshooting step is unset CUDA_VISIBLE_DEVICES and a restart. A quick test with the Hunyuan 3 GPU Info node (also in this pack) will show you torch.cuda.device_count() and whether the second card is actually visible.

Installing

cd ComfyUI/custom_nodes
git clone https://github.com/EricRollei/Comfy_HunyuanImage3
cd Comfy_HunyuanImage3
pip install -r requirements.txt

Restart ComfyUI (or ComfyUI Manager, search "Comfy_HunyuanImage3"). Requirements include accelerate>=1.2.1, which is what does the device-map distribution.

The honest read

Multi-GPU BF16 is the "I refuse to quantize" tax: full quality, but you're paying in complexity, PCIe transfers, and troubleshooting. If your goal is just output quality on two mid-range cards, NF4 on one card is dramatically simpler and - at typical 1MP renders - competitive. This loader is for people who want the full-precision reference quality and already own the second card. And note the README flags multi-GPU as the least-tested area of the pack; the author lists "test and document multi-GPU setup" as unfinished work. It works, but it's the frontier.