Z-Image i2L v2 — Loader

The Loader is where this pack both starts and stumbles. It's the node that pulls down the Z-Image model plus DiffSynth-Studio's i2L v2 template, and "pulls down" is doing heavy lifting here: the first run downloads tens of gigabytes from ModelScope and loads them into memory. That's a one-time cost, and every other node in this pack hangs off the two things this one outputs.

What you're actually loading: Z-Image is Alibaba Tongyi-MAI's 6B image model - the one that made Flux 2 Dev's launch week uncomfortable by being a fraction of the size and VRAM. i2L v2 is DiffSynth-Studio's image-to-LoRA hypernetwork: it looks at a few reference images and predicts a style LoRA in a single forward pass, no training. The Loader builds the base ZImagePipeline (transformer, text encoder, VAE), enables hot loading so a predicted LoRA can be dropped onto the transformer at generation time, then loads the i2L v2 TemplatePipeline that does the actual extraction.

The inputs that matter:

• device - cuda is the default and realistically the only one that works. mps and cpu are in the dropdown, but the upstream pipeline is CUDA-oriented; pick cuda on a non-CUDA box and you get a clear error instead of a silent crash.
• low_vram - on by default, leave it on. It keeps the big weights on CPU and streams them to the GPU only when needed, which is what lets a 24 GB card run this at all. On 32 GB or more you can flip it off for speed.
• base_model - this one matters more than it looks. z-image (the default) is what i2L generation expects: cfg ~4, 50 steps. But the Z-Image ControlNet Union is trained for z-image-turbo, so the ControlNet Sample node requires switching to turbo here or you'll get noise. Pick based on which sample node you're using.
• load_controlnet - only for the ControlNet workflow; downloads Alibaba-PAI's Union 2.1 on top.
• modelscope_cache - optional string that points the model cache somewhere with space. Handy on a rented box where the home directory is small.

It returns two things: pipe (the Z-Image pipeline, into any Sample or Generate node) and template (the i2L template, into Extract LoRA or Generate). Generate needs both; Extract LoRA needs only the template.

Install

Install through ComfyUI Manager (search ComfyUI_ZImageI2L_v2) or clone it:

cd ComfyUI/custom_nodes
git clone https://github.com/jzhang-POP/ComfyUI_ZImageI2L_v2

The part that bites is the dependency. This pack targets the v2 Diffusion Templates API in DiffSynth-Studio, and the PyPI build of DiffSynth can lag it. You need the git install, not pip:

git clone https://github.com/modelscope/DiffSynth-Studio.git
cd DiffSynth-Studio && pip install -e . && cd ..
pip install -r ComfyUI/custom_nodes/ComfyUI_ZImageI2L_v2/requirements.txt  # just modelscope + safetensors

Restart ComfyUI, then run the Loader once. The model download happens on that first run.

Common issues

The classic failure is an import error mentioning TemplatePipeline - that's DiffSynth installed from PyPI instead of git. The node literally prints the fix (the two commands above). Verify with a one-liner: from diffsynth.diffusion.template import TemplatePipeline should import clean.

Beyond that it's the usual suspects: OOM on first run means low_vram got switched off; a slow first generation is the model download, not your GPU; and if you're on a Blackwell 5090 you'll want a cu128+ PyTorch build - a 4090 with stock ComfyUI PyTorch is the known-good baseline. Give this node a warm-up run before you build the workflow around it, because everything downstream silently waits on it.