Z-Image Turbo Loader (ModelScope)

This is the front door to tpc2233's Z-Image-Turbo pack, and it does exactly one thing: pull Alibaba's Tongyi-MAI/Z-Image-Turbo diffusers pipeline into memory and hand it off as a single object the sampler node can use. Nothing renders here - it's setup. But it's worth understanding because it's also where most of the pack's real footguns live.

Why this node exists at all

If you've built ComfyUI workflows before, you're used to loading a model as three or four separate pieces - checkpoint, CLIP, VAE - wired into a KSampler. This pack does something different, and it says so right in its own README: it runs Z-Image "native weights." Z-Image ships from Alibaba as a diffusers pipeline, not the safetensors checkpoint format ComfyUI's built-in loaders expect. So instead of splitting it up, this node loads the whole diffusers pipe as one opaque ZIMAGE_PIPE blob and passes it straight to ZImageSampler, which does prompt encoding, denoising, and decoding internally. You're trading ComfyUI's usual modularity for "load the model the way its own team ships it."

The "(ModelScope)" in the display name is the other half of the story: rather than pulling from Hugging Face, this loader fetches through Alibaba's own ModelScope hosting via the modelscope Python package. Same weights, different distribution channel - which matters mainly for install, covered below.

The inputs that matter

There are only four, all required, no optional inputs at all:

• model_id (default Tongyi-MAI/Z-Image-Turbo) - the ModelScope repo to pull. Leave it alone unless you're deliberately pointing at a mirror or fine-tune published in the same diffusers-pipeline layout.
• precision - bf16 (default), fp16, or fp32. bf16 is the sane default: full-precision-adjacent quality with half the VRAM of fp32, and no compatibility surprises. Drop to fp16 only if you know your setup wants it; reach for fp32 only if you're debugging or stuck on CPU.
• compile_model (default false) - runs the model through torch.compile. It buys you faster steps after the first one, at the cost of a genuinely slow first compile. Worth flipping on if you're going to sit and generate for a while; skip it for a one-off image, the compile overhead will eat any gain.
• attention_backend - default, flash, or flash_3. FlashAttention variants need the flash-attn package and compatible hardware; flash_3 specifically is FlashAttention-3, which is Hopper-only (H100-class cards). Pick default unless you know you have the stack for the faster ones - asking for flash_3 on a 3060 or 4090 just won't work.

The one output is pipe (ZIMAGE_PIPE), and it goes into exactly one place: the pipe input on ZImageSampler.

How to install it

Per the pack's own README, you've got two routes:

• ComfyUI Manager - search "ComfyUI-Z-Image-Turbo," install, restart.
• Manual:

  cd ComfyUI/custom_nodes
  git clone https://github.com/tpc2233/ComfyUI-Z-Image-Turbo.git
  cd ComfyUI-Z-Image-Turbo
  pip install modelscope
  pip install git+https://github.com/huggingface/diffusers
  pip install -r requirements.txt
  

That second pip install line is worth pausing on. It's installing diffusers straight from the GitHub main branch, not a pinned PyPI release - almost certainly because Z-Image support hadn't landed in a tagged diffusers version yet when this pack was written. That's a real trade-off, not a nitpick: ComfyUI custom nodes share one Python environment, so a git-main diffusers install can silently upgrade (or break) whatever version another node pack expected. If you've got other diffusers-dependent custom nodes installed, keep an eye on them after adding this one.

The model itself isn't part of the install - per the README, it auto-downloads to ComfyUI/models/diffusers/Z-Image-Turbo the first time you actually run a workflow through this loader. Your first generation will sit there looking stuck while a multi-gigabyte download happens in the background; that's normal, not a hang.

Common issues & troubleshooting

No quantized/low-VRAM option here. precision only offers bf16/fp16/fp32 - there's no FP8 or GGUF path in this loader, even though the wider Z-Image community has built exactly those for cards under 12GB. If you're VRAM-constrained, this specific pack's loader isn't going to get you there; you'd be looking at one of the community GGUF/FP8 forks instead.

flash_3 errors out or silently does nothing. That backend needs Hopper (H100-class) hardware. On anything else, use default.

Something else in your Python env breaks after installing this. Check whether it's the diffusers-from-git install stepping on another node pack's pinned version - this is the most likely culprit given how the requirements are structured.

First run takes forever. That's the model auto-downloading, not an error. Let it finish; check your terminal/console log if you want to confirm it's actually pulling data rather than stalled.