How to Install & Run Z-Image-Turbo Locally (Python, Diffusers & Low-VRAM Guide)

This guide walks through installing and running Z-Image-Turbo (Tongyi-MAI/Z-Image-Turbo) locally on Linux, Windows, or macOS. Built on Alibaba Tongyi Lab's 6B-parameter Scalable Single-Stream Diffusion Transformer (S3-DiT) architecture, Z-Image-Turbo generates photorealistic 1024×1024 images and accurate bilingual (English & Chinese) typography in 8 NFEs (num_inference_steps=9, guidance_scale=0.0).

Don't have a 16 GB VRAM GPU? You can skip the 12 GB+ weight download and generate images in under a second on cloud GPUs—sign in on the Z-Image Online Workspace or test the Z-Image-Turbo Playground to claim free starter credits.

Hardware & Software Prerequisites

To run the full bfloat16 pipeline smoothly on your workstation, verify the following requirements:

• GPU Recommended: NVIDIA GPU with 16 GB VRAM or more (e.g., RTX 4080, RTX 4090, RTX 3090, A10G, L4, or H100).
• 8 GB – 12 GB VRAM GPUs: Supported via sequential CPU offloading (enable_model_cpu_offload()) or quantized GGUF / FP8 weights in ComfyUI, with slower per-image latency.
• System RAM & Disk: At least 24 GB system RAM and ~20 GB free SSD space for model checkpoints.
• Software: Python 3.10+ and an active NVIDIA CUDA 12.1+ installation.

1. Create an Isolated Virtual Environment

Isolating Python dependencies avoids version conflicts with existing PyTorch or Diffusers installations. Open your terminal and create a virtual environment named zimage-env:

python -m venv zimage-env

Activate the virtual environment:

# Linux or macOS
source zimage-env/bin/activate

# Windows (Command Prompt / PowerShell)
zimage-env\Scripts\activate

2. Install PyTorch and Hugging Face Diffusers

Install a CUDA-enabled build of PyTorch (the command below targets CUDA 12.4; adjust --index-url if your driver uses CUDA 12.1 or 12.6). Because ZImagePipeline requires recent S3-DiT support, install diffusers from source along with transformers, accelerate, and safetensors:

pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install git+https://github.com/huggingface/diffusers
pip install transformers accelerate safetensors

3. Load the Z-Image-Turbo Pipeline

Create a Python file (for example, run_zimage.py) and load Tongyi-MAI/Z-Image-Turbo using torch.bfloat16 precision for optimal memory efficiency without quality loss:

import torch
from diffusers import ZImagePipeline

pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.bfloat16,
    low_cpu_mem_usage=False,
)
pipe.to("cuda")

4. Generate a 1024×1024 Image (8 NFEs)

Unlike traditional 25–50 step diffusion models, Z-Image-Turbo uses Decoupled-DMD step distillation:

• Set num_inference_steps=9 (which corresponds to 8 DiT forward evaluations / NFEs).
• Keep guidance_scale=0.0—distilled Turbo weights have guidance baked in and do not require Classifier-Free Guidance (CFG).

prompt = (
    "Cinematic night street in rain, neon storefront sign clearly reading "
    "'MIDNIGHT ROASTERY' in warm gold lettering, wet asphalt reflections, 35mm f/1.4"
)

image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=9,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("z_image_turbo_output.png")

5. Performance Optimization (Flash Attention & Torch Compile)

On Ampere, Ada Lovelace, or Hopper GPUs (RTX 30/40 series, A100, H100), enabling Flash Attention 2 or Flash Attention 3 and torch.compile significantly reduces inference latency after the initial warm-up pass:

# Use Flash Attention 2 (or "_flash_3" on Hopper GPUs)
pipe.transformer.set_attention_backend("flash")

# Optional: compile the S3-DiT backbone for faster repeated inference
# pipe.transformer.compile()

6. Low-VRAM Mode (8 GB – 12 GB GPUs)

If you encounter CUDA Out-Of-Memory (OOM) errors on 8 GB or 12 GB graphics cards, replace pipe.to("cuda") with CPU offloading so inactive submodules reside in system RAM until needed:

import torch
from diffusers import ZImagePipeline

pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()

Fine-Tuning vs. Instant Inference

• Need custom LoRA training, ControlNet conditioning, or full Classifier-Free Guidance (CFG)? Explore the foundational checkpoint on our Z-Image-Base Model Page.
• Prefer zero local setup? Launch Z-Image-Turbo Online directly in your browser.