README.md

---
license: other
license_name: qwen-research
license_link: LICENSE
base_model: Qwen/Qwen-Image-2.1-Turbo
base_model_relation: quantized
library_name: mlx-serve
tags:
  - mlx
  - mlx-serve
  - quantized
  - text-to-image
  - image-to-image
pipeline_tag: text-to-image
---

# Qwen-Image-2.1-Turbo MLX-Serve 8-bit

8-bit pack of [Qwen/Qwen-Image-2.1-Turbo](https://huggingface.co/Qwen/Qwen-Image-2.1-Turbo) for
[mlx-serve](https://mlxserve.com/): 17.7 GB, for 32 GB Macs. The same text rendering as bf16 at the same seed.

![sample](https://huggingface.co/ddalcu/Qwen-Image-2.1-Turbo-MLX-Serve-8bit/resolve/main/sample.jpg)

## Run it

Download **[MLX-Serve.app](https://github.com/ddalcu/mlx-serve/releases/latest)**,
open the Image tab, and pick **Qwen-Image 2.1 Turbo 8-bit** from the model menu.
It downloads with a progress bar and generates in the same window. No terminal,
nothing to configure.

Prefer Homebrew? It is a third-party tap, so tap it first:

```bash
brew tap ddalcu/mlx-serve https://github.com/ddalcu/mlx-serve
brew trust ddalcu/mlx-serve
brew install --cask mlx-serve
```

Driving it from code instead? The app runs the server on `http://localhost:11234`:

```sh
curl localhost:11234/v1/images/generations -H 'Content-Type: application/json' \
  -d '{"model":"ddalcu/Qwen-Image-2.1-Turbo-MLX-Serve-8bit","prompt":"a red fox in fresh snow","size":"1024x1024"}'
```

8 steps, always: the pack's own sampling schedule (`sample_sigmas` in `model_index.json`)
decides, and a requested `steps` is ignored, as in diffusers. Needs mlx-serve 26.10.2 or
newer; an older build runs the base model's 40-step schedule on it. Guidance is 1 by
default; `guidance_scale` above 1 with a `negative_prompt` runs real CFG (two forwards per
step). `image` + `strength` does image-to-image, and `"mode":"edit"` with an `image` (plus
up to 9 `ref_images`) edits it from the prompt.

## Measured (M5 Ultra, 256 GB)

| Pack | 1024x1024 text-to-image | Instruction edit, 1 reference | Peak memory |
|---|---|---|---|
| bf16 (`Qwen/Qwen-Image-2.1-Turbo`) | 7.2 s | 11.2 s | 31.4 GB |
| 8-bit | 7.8 s | 12.5 s | 19.3 GB |
| 4-bit | 8.8 s | 11.9 s | 12.8 GB |

Per request with the model loaded, 8 steps; peak is MLX's own across the request with
everything resident. Quantizing saves memory, not time, on a Mac this size. On a Mac the
full set would crowd, mlx-serve loads the text encoder per request and frees it before the
denoise, so the resident set is the DiT and VAE.

## mlx-serve

A native Zig server for Apple Silicon. No Python, no cloud, no Electron. One
9 MB binary.

- **One server, every modality.** Chat, images, video, music, speech with voice
  cloning, and 3D, all running natively on MLX.
- **Points at what you already use.** OpenAI- *and* Anthropic-compatible APIs on
  `http://localhost:11234`, so Claude Code, the OpenAI SDK, Continue, Cursor and
  Open WebUI just work.
- **Any LLM, not just these.** Every MLX model and every GGUF on Hugging Face,
  with speculative decoding built in.
- **MLX-Serve.app included.** Signed macOS menu-bar app: chat, agent mode with
  MCP tools, model downloads, and every generator above, no terminal needed.

[mlxserve.com](https://mlxserve.com/) · [GitHub](https://github.com/ddalcu/mlx-serve)

If it is useful to you, a star on
[GitHub](https://github.com/ddalcu/mlx-serve) genuinely helps.

## What is in it

The checkpoint's own diffusers layout and key names, with the DiT block linears and the
text-encoder layer linears affine-quantized to 8-bit (group 64). Kept dense: the VAE
(f32), `embed_tokens`, norms, and the DiT's small or shared linears. Kept: the Qwen3-VL
vision tower, for instruction editing. Dropped: `lm_head` and the VAE's per-frame `time_conv`s.
Built by `tests/convert_qwen_image21_weights.py --preset 32gb` in the mlx-serve repo.

Qwen is licensed under the Qwen RESEARCH LICENSE AGREEMENT, Copyright (c) 2026 Hangzhou
Tongyi Laboratory Technology Co., Ltd. All Rights Reserved. **Non-commercial use only**:
see [LICENSE](LICENSE) and [NOTICE](NOTICE). The original model and weights are by the Qwen team.