### Download Z-Image-Turbo model

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo?library=diffusers

Install the huggingface_hub library and use the hf download command to get the Z-Image-Turbo model. Set the environment variable for high performance.

```bash
pip install -U huggingface_hub
HF_XET_HIGH_PERFORMANCE=1 hf download Tongyi-MAI/Z-Image-Turbo

```

--------------------------------

### Install Diffusers from Source

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/43

If you encounter issues with the standard installation, uninstall the current diffusers package and install it directly from the GitHub repository. This can resolve compatibility problems.

```bash
! pip uninstall diffusers
! pip install git+https://github.com/huggingface/diffusers.git -U
```

--------------------------------

### Install Diffusers Library

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/100

Install the necessary libraries for using the Diffusers pipeline. This includes diffusers, transformers, and accelerate.

```bash
pip install -U diffusers transformers accelerate
```

--------------------------------

### Quick Start: Generate an image with Z-Image Pipeline

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo?library=diffusers

Load the ZImagePipeline, set up the device and data type, and generate an image using a prompt. Guidance scale should be 0 for Turbo models.

```python
import torch
from diffusers import ZImagePipeline

# 1. Load the pipeline
# Use bfloat16 for optimal performance on supported GPUs
pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.bfloat16,
    low_cpu_mem_usage=False,
)
pipe.to("cuda")

# [Optional] Attention Backend
# Diffusers uses SDPA by default. Switch to Flash Attention for better efficiency if supported:
# pipe.transformer.set_attention_backend("flash")    # Enable Flash-Attention-2
# pipe.transformer.set_attention_backend("_flash_3") # Enable Flash-Attention-3

# [Optional] Model Compilation
# Compiling the DiT model accelerates inference, but the first run will take longer to compile.
# pipe.transformer.compile()

# [Optional] CPU Offloading
# Enable CPU offloading for memory-constrained devices.
# pipe.enable_model_cpu_offload()

prompt = "Young Chinese woman in red Hanfu, intricate embroidery. Impeccable makeup, red floral forehead pattern. Elaborate high bun, golden phoenix headdress, red flowers, beads. Holds round folding fan with lady, trees, bird. Neon lightning-bolt lamp (⚡️), bright yellow glow, above extended left palm. Soft-lit outdoor night background, silhouetted tiered pagoda (西安大雁塔), blurred colorful distant lights."

# 2. Generate Image
image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=9,  # This actually results in 8 DiT forwards
    guidance_scale=0.0,     # Guidance should be 0 for the Turbo models
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("example.png")

```

--------------------------------

### Install Diffusers Library

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/colab

Installs the diffusers library, which is necessary for running diffusion models.

```bash
!pip install -U diffusers
```

--------------------------------

### Install Diffusers from Source

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/2

If encountering issues with the standard diffusers package, install it directly from its GitHub repository. This is often required for custom pipelines like ZImagePipeline.

```bash
pip install git+https://github.com/huggingface/diffusers.git -U
```

--------------------------------

### Run Inference with ZImagePipeline from Source

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/2

Load and use the ZImagePipeline after installing diffusers from source and potentially downloading weights locally. This ensures the custom pipeline is recognized.

```python
import torch
# This import requires the source installation from step 1
from diffusers import ZImagePipeline
```

--------------------------------

### Install Z-Image Turbo Diffusers

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo

Install the latest version of the diffusers library from source to enable Z-Image support. This command ensures you have the most up-to-date features.

```bash
pip install git+https://github.com/huggingface/diffusers
```

--------------------------------

### Accelerated Image Generation with Flash SDPA

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/139

Utilize Flash SDPA for significantly faster image generation, achieving up to 25% speed improvement. This example demonstrates loading the ZImagePipeline and using the '_native_flash' attention backend for optimized performance. It also includes parameters for high-resolution image generation and specific guidance settings.

```python
import torch
from diffusers import ZImagePipeline
from diffusers.models.attention_dispatch import attention_backend

# Load the pipeline
pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image",
    torch_dtype=torch.bfloat16,
    low_cpu_mem_usage=True,
)
pipe.enable_model_cpu_offload()

# Generate image
prompt = "Two young Asian women stand close together against a backdrop of a plain gray textured wall, possibly an indoor carpeted floor. The woman on the left has long, curly hair, wears a navy blue sweater with cream-colored ruffles on the left sleeve, a white stand-up collar shirt underneath, and white trousers; she wears small gold earrings"
negative_prompt = "" # Optional, but would be powerful when you want to remove some unwanted content

with attention_backend("_native_flash"):
    image = pipe(
        prompt=prompt,
        negative_prompt=negative_prompt,
        height=1920,
        width=1088,
        cfg_normalization=False,
        num_inference_steps=50,
        guidance_scale=4,
        generator=torch.Generator("cuda").manual_seed(42),
    ).images[0]

image.save("example.png")

```

--------------------------------

### Environment Activation and Script Execution

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/2

Demonstrates a command for activating a Conda environment and running a Python script. This is often used in development setups.

```bash
conda_hook && conda deactivate && conda deactivate && conda deactivate && conda activate base && D:\pinokio\api\Z-Image-Pinokio.git\env\Scripts\activate D:\pinokio\api\Z-Image-Pinokio \env && python app.py
```

--------------------------------

### Import Error Example

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/2

Shows a typical ImportError when 'ZImagePipeline' cannot be imported from the 'diffusers' library. This may indicate an installation or path issue.

```bash
Traceback (most recent call last):
  File "D:\pinokio\api\Z-Image-Pinokio.git\app.py", line 3, in 
    from diffusers import ZImagePipeline
ImportError: cannot import name 'ZImagePipeline' from 'diffusers' (D:\pinokio\api\Z-Image-Pinokio.git\env\lib\site-packages\diffusers__init__.py)
```

--------------------------------

### Load and Initialize ZImagePipeline

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/84

Loads the transformer and text encoder models, then builds the ZImagePipeline. Ensure `torch_dtype` and `device_map` are set appropriately for your hardware. Models are loaded directly from a specified path.

```python
transformer = ZImageTransformer2DModel.from_pretrained(
    tr_path,
    torch_dtype=torch.bfloat16,
    device_map="auto" 
)

print("INFO: Loading Text Encoder from disk...")
text_encoder = AutoModel.from_pretrained(
    te_path,
    torch_dtype=torch.bfloat16,
    device_map="auto"
)

# 2. Build Pipeline
print("INFO: Building pipeline...")
pipe = ZImagePipeline.from_pretrained(
    model_id,
    transformer=transformer,
    text_encoder=text_encoder,
    torch_dtype=torch.bfloat16,
)

# 3. Memory Settings (From your example)
# Since you used device_map="auto" above, the models are already on GPU.
# We skip CPU offload to match your "THIS WORKS" example which prefers GPU speed.
# If you crash, uncomment the offload line below.
# pipe.enable_model_cpu_offload() 
pipe.to(device)
```

--------------------------------

### Build zimage-ncnn-vulkan from Source

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/145

Clone the zimage-ncnn-vulkan repository, initialize submodules, and build the project using CMake. This process compiles the native C++ implementation.

```bash
git clone https://github.com/nihui/zimage-ncnn-vulkan.git
cd zimage-ncnn-vulkan
git submodule update --init --recursive --depth 1
mkdir build && cd build
cmake ../src
cmake --build . -j 4
```

--------------------------------

### Download Model Weights Locally

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/2

Download the model weights to a local directory to avoid potential version conflicts with the Hugging Face Hub. This is a workaround for hub versioning issues.

```bash
huggingface-cli download --resume-download Tongyi-MAI/Z-Image-Turbo --local-dir "./Z-Image-Turbo"
```

--------------------------------

### Load ZImagePipeline from Local Path

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/2

Loads the ZImagePipeline from a local directory. Ensure the model weights are downloaded to the specified path.

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

--------------------------------

### Quantize and Run Z-Image-Turbo Model

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/64

This script loads the Z-Image-Turbo model, applies 4-bit quantization to the transformer and text encoder, and then generates an image. It requires a CUDA-enabled GPU and allows for CPU offloading to reduce VRAM usage. Ensure `torch_dtype` is set appropriately for your hardware.

```python
import torch

from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig
from diffusers import ZImagePipeline, AutoModel
from transformers import BitsAndBytesConfig as TransformersBitsAndBytesConfig

model_cache = "./weights/"
model_id = "Tongyi-MAI/Z-Image-Turbo"
torch_dtype = torch.bfloat16
USE_CPU_OFFLOAD = False


if torch.cuda.is_available():
    print(f"INFO: CUDA available: {torch.cuda.get_device_name(0)} (count={torch.cuda.device_count()})")
    device = "cuda:0"
    gpu_id = 0
else:
    raise RuntimeError("ERROR: CUDA not available. This program requires a CUDA-enabled GPU.")



print("INFO: Loading transformer block ...")
quantization_config = DiffusersBitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
    llm_int8_skip_modules=["transformer_blocks.0.img_mod"],
)
transformer = AutoModel.from_pretrained(
    model_id,
    cache_dir=model_cache,
    subfolder="transformer",
    quantization_config=quantization_config,
    torch_dtype=torch_dtype,
    device_map=device,
)
print("INFO: Transformer block loaded.")
if USE_CPU_OFFLOAD:
    transformer = transformer.to("cpu")


print("INFO: Loading text encoder ...")
quantization_config = TransformersBitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)
text_encoder = AutoModel.from_pretrained(
    model_id,
    cache_dir=model_cache,
    subfolder="text_encoder",
    quantization_config=quantization_config,
    torch_dtype=torch_dtype,
    device_map=device,
)
print("INFO: Text encoder loaded.")
if USE_CPU_OFFLOAD:
    text_encoder = text_encoder.to("cpu")


print("INFO: Building pipeline ...")
pipe = ZImagePipeline.from_pretrained(
    model_id,
    transformer=transformer,
    text_encoder=text_encoder,
    torch_dtype=torch_dtype,
)
print("INFO: Pipeline constructed")

if USE_CPU_OFFLOAD:
    pipe.enable_model_cpu_offload(gpu_id=gpu_id)
    print("INFO: CPU offload active")
else:
    pipe.to(device)
    print("INFO: Pipeline to gpu")



prompt = "Realistic mid-aged male image"

image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=9,  # This actually results in 8 DiT forwards
    guidance_scale=0.0,     # Guidance should be 0 for the Turbo models
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("example.png")

```

--------------------------------

### Basic Z-Image Native Usage

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/145

Run Z-Image natively using the zimage-ncnn-vulkan executable with a basic prompt and output file. This requires no Python or PyTorch dependencies.

```bash
# Basic usage
zimage-ncnn-vulkan -p "a wandering astronaut on mars, photo realistic, 8k" -o output.png
```

--------------------------------

### Generate Image with Z-Image-Turbo

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/100

Load the Tongyi-MAI/Z-Image-Turbo model and generate an image from a text prompt using PyTorch and Diffusers. Ensure you have a CUDA-enabled GPU for optimal performance.

```python
import torch
from diffusers import DiffusionPipeline

# switch to "mps" for apple devices
pipe = DiffusionPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16, device_map="cuda")

prompt = "Astronaut in a jungle, cold color palette, muted colors, detailed, 8k"
image = pipe(prompt).images[0]
```

--------------------------------

### Project Dependencies for Z-Image-Turbo

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/64

This `pyproject.toml` file specifies the project name, version, and essential dependencies for running the Z-Image-Turbo model, including specific versions of PyTorch with CUDA support and libraries like `diffusers` and `transformers`. It also configures UV sources for PyTorch wheels.

```toml
[project]
name = "z_image_turbo_q"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "torch==2.5.1+cu124",
    "torchvision==0.20.1+cu124",
    "torchaudio==2.5.1+cu124",
    "diffusers",
    "transformers>=4.57.1",
    "accelerate>=1.12.0",
    "bitsandbytes>=0.48.2",
    "ftfy>=6.3.1",
    "imageio-ffmpeg>=0.6.0",
    "imageio>=2.37.2",
    "ipykernel>=7.1.0",
]

[tool.uv.sources]
torch = { index = "torch-cuda" }
torchvision = { index = "torch-cuda" }
torchaudio = { index = "torch-cuda" }
diffusers = { git = "https://github.com/huggingface/diffusers" }

[[tool.uv.index]]
name = "torch-cuda"
url = "https://download.pytorch.org/whl/cu124"
explicit = true


```

--------------------------------

### Load Quantized Z-Image-Turbo Models

Source: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/discussions/84

Load the previously quantized text encoder and transformer models from disk to run the Z-Image-Turbo pipeline. This script requires CUDA to be available and checks for the existence of the quantized model files.

```python
import torch
import os
import sys
from diffusers import ZImagePipeline, ZImageTransformer2DModel
from transformers import AutoModel

# --- Configuration ---
model_id = "Tongyi-MAI/Z-Image-Turbo"
te_path = r"D:\temp\z_turbo_te_bnb"
tr_path = r"D:\temp\z_turbo_tr_bnb"

# Verify files exist
if not os.path.exists(te_path) or not os.path.exists(tr_path):
    print("❌ Error: Quantized models not found in D:\temp.")
    print("   Please run Step 1 and Step 2 scripts first.")
    sys.exit(1)

print("--- ⚡ Z-Image-Turbo (Saved Quants Load) ---")

if torch.cuda.is_available():
    device = "cuda:0"
    print(f"INFO: CUDA available: {torch.cuda.get_device_name(0)}")
else:
    raise RuntimeError("ERROR: CUDA not available.")

# 1. Load the Saved Quants
print("INFO: Loading Transformer from disk...")
```