moonbox-ai/Z-Image-Turbo-MLX

Z-Image-Turbo MLX

MLX builds of Z-Image-Turbo, made by Moonbox for Apple Silicon Macs. Each precision is a folder; keep a folder's files together. Only the parts listed below are converted: the rest of the pipeline comes from the original repository unless the section below says otherwise.

Files

The last column is how far each build is from the original PyTorch model on the same inputs (see the section below for what was measured).

Precision	File	Size	sha256	Checked against the original
bf16	bf16/mflux_model.json	0.4 kB	82aac4aab78f	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/text_encoder/0.safetensors	2.14 GB	d9da5eee77aa	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/text_encoder/1.safetensors	2.12 GB	21bc20095866	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/text_encoder/2.safetensors	2.12 GB	22617bc5ebe6	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/text_encoder/3.safetensors	1.66 GB	2f5cf62a722c	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/text_encoder/model.safetensors.index.json	22.9 kB	a37d814cbc0a	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/tokenizer/chat_template.jinja	4.2 kB	a55ee1b16601	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/tokenizer/tokenizer.json	11.4 MB	be75606093db	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/tokenizer/tokenizer_config.json	0.7 kB	1cc816812993	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/transformer/0.safetensors	2.09 GB	30d27b9e25de	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/transformer/1.safetensors	2.09 GB	b64e74b43702	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/transformer/2.safetensors	2.09 GB	4e2ae217bc4a	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/transformer/3.safetensors	2.14 GB	54a0e97b1a75	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/transformer/4.safetensors	2.14 GB	bfe37ec4ec90	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/transformer/5.safetensors	1.75 GB	8545b1fb9bdd	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/transformer/model.safetensors.index.json	29.7 kB	7a6841af938d	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/vae/0.safetensors	167.7 MB	ca34451d9193	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
bf16	bf16/vae/model.safetensors.index.json	16.3 kB	e3834c6ff50a	PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst
8bit	8bit/mflux_model.json	0.4 kB	68820777b037	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/text_encoder/0.safetensors	2.15 GB	4756c0deba13	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/text_encoder/1.safetensors	2.13 GB	d3175a404177	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/text_encoder/model.safetensors.index.json	51.3 kB	b92fbec4b1fe	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/tokenizer/chat_template.jinja	4.2 kB	a55ee1b16601	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/tokenizer/tokenizer.json	11.4 MB	be75606093db	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/tokenizer/tokenizer_config.json	0.7 kB	1cc816812993	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/transformer/0.safetensors	2.13 GB	0ed0f24a2983	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/transformer/1.safetensors	2.15 GB	7f2063711f79	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/transformer/2.safetensors	2.13 GB	7aa3cd2e7306	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/transformer/3.safetensors	129.6 MB	89daaf83b97b	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/transformer/model.safetensors.index.json	61.6 kB	3deb0349ca67	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/vae/0.safetensors	165.7 MB	cba8dc410ab2	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
8bit	8bit/vae/model.safetensors.index.json	17.4 kB	a4a46b43b530	below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst
6bit	6bit/mflux_model.json	0.4 kB	4473625f76d8	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/text_encoder/0.safetensors	2.14 GB	8f025c99044b	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/text_encoder/1.safetensors	1.13 GB	3830cc1f9390	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/text_encoder/model.safetensors.index.json	51.3 kB	5d9c5b6ad65b	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/tokenizer/chat_template.jinja	4.2 kB	a55ee1b16601	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/tokenizer/tokenizer.json	11.4 MB	be75606093db	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/tokenizer/tokenizer_config.json	0.7 kB	1cc816812993	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/transformer/0.safetensors	2.14 GB	973ba309094e	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/transformer/1.safetensors	2.14 GB	fdd39290bb7c	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/transformer/2.safetensors	723.2 MB	69fa2a1d701b	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/transformer/model.safetensors.index.json	61.6 kB	558852a66f31	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/vae/0.safetensors	165.2 MB	ae30e4e6c93e	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
6bit	6bit/vae/model.safetensors.index.json	17.4 kB	e287457d19ea	below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst
4bit	4bit/mflux_model.json	0.4 kB	af71e0c5fca8	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/text_encoder/0.safetensors	2.14 GB	65b5e0fac735	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/text_encoder/1.safetensors	127.6 MB	adc84cd2f289	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/text_encoder/model.safetensors.index.json	51.3 kB	a5d86c766488	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/tokenizer/chat_template.jinja	4.2 kB	a55ee1b16601	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/tokenizer/tokenizer.json	11.4 MB	be75606093db	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/tokenizer/tokenizer_config.json	0.7 kB	1cc816812993	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/transformer/0.safetensors	2.14 GB	a81159ebd7ff	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/transformer/1.safetensors	1.32 GB	ef02d88179ed	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/transformer/model.safetensors.index.json	61.6 kB	204a023adee4	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/vae/0.safetensors	164.7 MB	1c8eaf3d17de	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst
4bit	4bit/vae/model.safetensors.index.json	17.4 kB	fb17ac2a8587	below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst

How to run

Each folder is the whole pipeline (Qwen3 text encoder, transformer, VAE, tokenizer) saved by mflux 0.24.0 from the original weights at the revision below. Run it with mflux:

pip install mflux==0.24.0
hf download moonbox-ai/Z-Image-Turbo-MLX --include "bf16/*" --local-dir zimage
mflux-generate-z-image-turbo --model zimage/bf16 --base-model z-image-turbo --steps 9 --guidance 0 \
  --prompt "A red fox in fresh snow at sunrise, photo" --width 1024 --height 1024 --seed 7 --output fox.png

8bit/, 6bit/ and 4bit/ quantize the transformer's and the text encoder's linear layers (MLX affine, group size 64); the VAE stays bf16. There is no fp16 folder: mflux computes in bf16 whatever the weights are.

How they were checked. The pipeline in mflux against diffusers' ZImagePipeline in PyTorch (bf16), started from the same initial noise, 3 prompts at 512x512, 9 steps. Pass: LPIPS <= 0.15 on every prompt. For scale, two seeds of the PyTorch pipeline are 12.9 dB / LPIPS 0.46 apart (a turbo model varies little between seeds).

Precision	Size	PSNR vs PyTorch (mean)	LPIPS (mean / worst)	Status
bf16/	20.5 GB	22.1 dB	0.118 / 0.147	passes
8bit/	11.0 GB	21.0 dB	0.141 / 0.201	below threshold, experimental; the same picture by eye
6bit/	8.5 GB	20.2 dB	0.164 / 0.227	below threshold, experimental: details change
4bit/	5.9 GB	17.0 dB	0.246 / 0.265	below threshold, experimental: details change

A 512x512 picture takes about 2.5 s (9 steps) on an Apple M5 with 24 GB, plus loading.

How these were made

From Z-Image-Turbo at revision f332072aa7: the original weights loaded in MLX and stored as bf16 or fp16, or quantized with MLX's affine quantization (8bit, 6bit, 4bit, group size 64; layers MLX can't quantize, such as convolutions and norms, stay bf16). Every build was checked against the original before upload; the sha256 column above is what the files must hash to.

License

Apache-2.0. These files are a derivative of the original model and carry its license: it is copied in this repository, and it governs your use of these files. The original model card follows unchanged.

---

Original model card

⚡️- Image
_{^{An Efficient Image Generation Foundation Model with Single-Stream Diffusion Transformer}}

                 

Welcome to the official repository for the Z-Image（造相）project!

✨ Z-Image

Z-Image is a powerful and highly efficient image generation model family with 6B parameters. Currently there are four variants:

• 🚀 Z-Image-Turbo – A distilled version of Z-Image that matches or exceeds leading competitors with only 8 NFEs (Number of Function Evaluations). It offers ⚡️sub-second inference latency⚡️ on enterprise-grade H800 GPUs and fits comfortably within 16G VRAM consumer devices. It excels in photorealistic image generation, bilingual text rendering (English & Chinese), and robust instruction adherence.

• 🎨 Z-Image – The foundation model behind Z-Image-Turbo. Z-Image focuses on high-quality generation, rich aesthetics, strong diversity, and controllability, well-suited for creative generation, fine-tuning, and downstream development. It supports a wide range of artistic styles, effective negative prompting, and high diversity across identities, poses, compositions, and layouts.

• 🧱 Z-Image-Omni-Base – The versatile foundation model capable of both generation and editing tasks. By releasing this checkpoint, we aim to unlock the full potential for community-driven fine-tuning and custom development, providing the most "raw" and diverse starting point for the open-source community.

• ✍️ Z-Image-Edit – A variant fine-tuned on Z-Image specifically for image editing tasks. It supports creative image-to-image generation with impressive instruction-following capabilities, allowing for precise edits based on natural language prompts.

📥 Model Zoo

Model	Pre-Training	SFT	RL	Step	CFG	Task	Visual Quality	Diversity	Fine-Tunability	Hugging Face	ModelScope
Z-Image-Omni-Base	✅	❌	❌	50	✅	Gen. / Editing	Medium	High	Easy	To be released	To be released
Z-Image	✅	✅	❌	50	✅	Gen.	High	Medium	Easy
Z-Image-Turbo	✅	✅	✅	8	❌	Gen.	Very High	Low	N/A
Z-Image-Edit	✅	✅	❌	50	✅	Editing	High	Medium	Easy	To be released	To be released

🖼️ Showcase

📸 Photorealistic Quality: Z-Image-Turbo delivers strong photorealistic image generation while maintaining excellent aesthetic quality.

📖 Accurate Bilingual Text Rendering: Z-Image-Turbo excels at accurately rendering complex Chinese and English text.

💡 Prompt Enhancing & Reasoning: Prompt Enhancer empowers the model with reasoning capabilities, enabling it to transcend surface-level descriptions and tap into underlying world knowledge.

🧠 Creative Image Editing: Z-Image-Edit shows a strong understanding of bilingual editing instructions, enabling imaginative and flexible image transformations.

🏗️ Model Architecture

We adopt a Scalable Single-Stream DiT (S3-DiT) architecture. In this setup, text, visual semantic tokens, and image VAE tokens are concatenated at the sequence level to serve as a unified input stream, maximizing parameter efficiency compared to dual-stream approaches.

📈 Performance

According to the Elo-based Human Preference Evaluation (on Alibaba AI Arena), Z-Image-Turbo shows highly competitive performance against other leading models, while achieving state-of-the-art results among open-source models.

Click to view the full leaderboard

🚀 Quick Start

Install the latest version of diffusers, use the following command:

^{Click here for details for why you need to install diffusers from source}

We have submitted two pull requests (#12703 and #12715) to the 🤗 diffusers repository to add support for Z-Image. Both PRs have been merged into the latest official diffusers release. Therefore, you need to install diffusers from source for the latest features and Z-Image support.

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

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")

🔬 Decoupled-DMD: The Acceleration Magic Behind Z-Image

Decoupled-DMD is the core few-step distillation algorithm that empowers the 8-step Z-Image model.

Our core insight in Decoupled-DMD is that the success of existing DMD (Distributaion Matching Distillation) methods is the result of two independent, collaborating mechanisms:

• CFG Augmentation (CA): The primary engine 🚀 driving the distillation process, a factor largely overlooked in previous work.
• Distribution Matching (DM): Acts more as a regularizer ⚖️, ensuring the stability and quality of the generated output.

By recognizing and decoupling these two mechanisms, we were able to study and optimize them in isolation. This ultimately motivated us to develop an improved distillation process that significantly enhances the performance of few-step generation.

🤖 DMDR: Fusing DMD with Reinforcement Learning

Building upon the strong foundation of Decoupled-DMD, our 8-step Z-Image model has already demonstrated exceptional capabilities. To achieve further improvements in terms of semantic alignment, aesthetic quality, and structural coherence—while producing images with richer high-frequency details—we present DMDR.

Our core insight behind DMDR is that Reinforcement Learning (RL) and Distribution Matching Distillation (DMD) can be synergistically integrated during the post-training of few-step models. We demonstrate that:

• RL Unlocks the Performance of DMD 🚀
• DMD Effectively Regularizes RL ⚖️

⏬ Download

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

📜 Citation

If you find our work useful in your research, please consider citing:

@article{team2025zimage,
  title={Z-Image: An Efficient Image Generation Foundation Model with Single-Stream Diffusion Transformer},
  author={Z-Image Team},
  journal={arXiv preprint arXiv:2511.22699},
  year={2025}
}

@article{liu2025decoupled,
  title={Decoupled DMD: CFG Augmentation as the Spear, Distribution Matching as the Shield},
  author={Dongyang Liu and Peng Gao and David Liu and Ruoyi Du and Zhen Li and Qilong Wu and Xin Jin and Sihan Cao and Shifeng Zhang and Hongsheng Li and Steven Hoi},
  journal={arXiv preprint arXiv:2511.22677},
  year={2025}
}

@article{jiang2025distribution,
  title={Distribution Matching Distillation Meets Reinforcement Learning},
  author={Jiang, Dengyang and Liu, Dongyang and Wang, Zanyi and Wu, Qilong and Jin, Xin and Liu, David and Li, Zhen and Wang, Mengmeng and Gao, Peng and Yang, Harry},
  journal={arXiv preprint arXiv:2511.13649},
  year={2025}
}