mlx-optiq
Pre-built quants · Hugging Face

A family of OptiQ quants. Ready to load.

Each model is a standard MLX checkpoint. Load it with mlx_lm.load(...), no special runtime. Sensitivity-driven mixed-precision quantization recovers what uniform quantization drops, from 4-bit at the small end where every layer counts, down to 2-bit on the largest mixture-of-experts models.

Quants built with mlx-optiq have been downloaded 250,000+ times in the last month across Hugging Face, between our mlx-community line and developers publishing their own OptiQ quants.

01 Mistral family · added Jul 23, 2026

Mistral: Devstral, the tool-calling coding model.

Mistral's Devstral is an agentic coding model on the Mistral-Small-3.1 base, which makes it also multimodal. OptiQ quantizes only the language tower and keeps the vision encoder at bf16 in a sidecar, so the one repo loads text-only under stock mlx-lm and full image+text under optiq serve. It clears uniform 4-bit by +1.95 Capability Score, winning five of six benchmarks, with +9 on long-context retrieval. The first OptiQ quant of a Mistral-family model.

Capability Score · 6-benchmark mean (MMLU + GSM8K + IFEval + BFCL + HumanEval + HashHop)
Model bf16 size mlx-optiq size Compression Capability Score Δ vs uniform-4
Devstral-Small-2-24B-Instruct-2512-OptiQ-4bit 45 GB 15.4 GB 2.9× 78.60 +1.95
Tool calls Devstral emits a tool call as [TOOL_CALLS]name[ARGS]{...}, terminated by EOS with no closing marker. A stock server treats that EOS as a stop and drops the call after one action. optiq serve captures the call and normalizes its arguments before templating, so multi-step agent loops keep running.
Image input The base is Mistral-Small-3.1, so the vision tower ships with the quant at bf16 in optiq/optiq_vision.safetensors and runs only when a request carries an image. Send an image_url part through optiq serve or the Lab.
The 119B model Mistral-Small-4-119B-2603-OptiQ-2bit is a 128-routed-expert sparse MoE. OptiQ ships it as a mixed 2/4-bit static build, 239 GB bf16 down to 43 GB, that runs on a 36 GB Mac by streaming its routed experts off SSD at about 11.8 GB resident. There is no Capability Score for it: at 2-bit that number is not meaningful, so it ships with a coherence check instead: it still writes working code at 2-bit.
Mistral getting-started guide →

02 Diffusion LLM family · added Jun 13, 2026

Diffusion LLM: OptiQ's first non-autoregressive family.

Diffusion language models are a different kind of model. They don't decode left-to-right; they iteratively un-mask a block of tokens over a handful of denoising steps. The family has two very different members: Google's DiffusionGemma-26B-A4B (block-diffusion, 128-expert MoE, image-text), and dhara-250m (tri-mode: AR + diffusion + self-speculation), a 250M model small enough to fine-tune on a laptop. OptiQ ships native, dependency-free decoders for both; for DiffusionGemma it lands a higher Capability Score on a smaller artifact, while dhara is held at 8-bit mixed precision, where it reproduces the bf16 reference exactly.

Capability Score · 6-benchmark mean (MMLU + GSM8K + IFEval + BFCL + HumanEval + HashHop)
Model bf16 size mlx-optiq size Compression Capability Score Δ vs published 4-bit
diffusiongemma-26B-A4B-it-OptiQ-4bit 51.6 GB 17.8 GB 2.9× 68.25 +4.12
dhara-250m-OptiQ-8bit 460 MB 357 MB 1.3× 7.83 KL 0.0005
Diffusion specifics DiffusionGemma is not loadable by stock mlx-lm/mlx-vlm; OptiQ ships a vendored, dependency-free decoder for it (mlx-optiq ≥ 0.2.3). Text + image generation and LoRA fine-tuning (a diffusion-native denoising loss) both work; optiq serve runs it with the fast confidence-threshold sampler by default (4.6–5× faster than the model's default). MTP / speculative drafting and KV-cache quant don't apply, the model is non-autoregressive and the parallel canvas un-masking is the native analog.
dhara-250m specifics A tri-mode tiny model built as a base to fine-tune, like Gemma-270M. Its mlx-native port registers with mlx-lm, so the whole OptiQ pipeline (convert, LoRA, eval, optiq serve, KV-quant) works. The recommended decode mode is self-speculation (--mtp): it drafts a block and AR-verifies it (two forwards per round), so output is identical to autoregressive decode but faster (~1.4× on M3 Max decoding greedily, several tokens per round). The model is overhead-bound, so the quant decodes at bf16 speed, the win is size, not throughput. At 250M there is no redundancy to spend, so the quant is tuned for fidelity: OptiQ holds 125 tensors at bf16 and drops 99 to 8-bit (10.25 bpw). Autoregressive and self-speculative decode are byte-identical to bf16 (KL 0.0005). The bit budget is set by KL, not by the Capability Score: at 250M that score cannot police a quant at all. A uniform 4-bit build of the same model diverges from bf16 120× more (KL 0.0594) and yet outscores both this quant and the bf16 model it came from. Details in the diffusion guide.
Diffusion LLM getting-started guide →

03 Nemotron 3 family · added Jun 3, 2026

Nemotron 3: NVIDIA's Mamba-attention hybrid.

NVIDIA's Nemotron 3 Nano interleaves Mamba2 state-space blocks with a handful of full-attention layers, and the larger model adds a 128-expert sparse MoE. The 30B-A3B (≈3 B active per token) gains the most: OptiQ assigns per-layer 4/8-bit across the fused routed experts and clears uniform 4-bit by a full +2.0 Capability Score, winning or tying all six benchmarks. The dense 4B gains less but still beats uniform 4-bit.

Capability Score · 6-benchmark mean (MMLU + GSM8K + IFEval + BFCL + HumanEval + HashHop)
Model bf16 size mlx-optiq size Compression Capability Score Δ vs uniform-4
NVIDIA-Nemotron-3-Nano-30B-A3B-OptiQ-4bit 63.2 GB 21 GB 3.0× 72.32 +2.11
NVIDIA-Nemotron-3-Nano-4B-OptiQ-4bit 7.9 GB 2.9 GB 2.7× 66.68 +0.24
Hybrid KV cache Only the four full-attention layers carry a KV cache; the Mamba2 blocks keep recurrent state instead. Each repo ships a kv_config.json covering just those attention layers (three at 4-bit, one at 8-bit). Point optiq serve --kv-config kv_config.json at it.
The Super 120B, streamed off SSD The largest in the family, Nemotron-3-Super-120B-A12B (512-expert hybrid MoE), runs on a 36 GB Mac as a 2-bit static quant (47.5 GB): about 14 GB resident, the 34 GB of routed experts streamed off SSD, ~3 tok/s. There is no Capability Score for it: at 2-bit that number is not meaningful, so it ships with a coherence check instead: it still writes working code at 2-bit. Read the write-up →
Nemotron 3 getting-started guide →

04 MiniCPM5 family · added May 28, 2026

MiniCPM5: a strong sub-gigabyte 1B.

OpenBMB's 1.08B-parameter Llama-architecture base, fully Apache-2.0. Hybrid-reasoning chat template with an enable_thinking flag. In non-thinking mode (the OptiQ benchmark recipe) it posts 52% MMLU, 65% IFEval, and 58% HumanEval on a model that weighs less than a gigabyte on disk. The OptiQ-4bit quant beats stock uniform-4 by 12 points on HumanEval and rescues HashHop from a 0% floor, same sensitivity-aware allocation story as the larger families.

Capability Score · 6-benchmark mean (MMLU + GSM8K + IFEval + BFCL + HumanEval + HashHop)
Model bf16 size mlx-optiq size Compression Capability Score Δ vs uniform-4
MiniCPM5-1B-OptiQ-4bit 2.1 GB 875 MB 2.4× 30.28 +4.44
Heads up MiniCPM5 ships a hybrid <think> reasoning mode. Pass chat_template_kwargs={"enable_thinking": true} to wake it up; expect substantially higher math/tool scores in that mode. OptiQ's benchmark recipe forces thinking off for cross-family comparability, so the table reflects fast-assistant performance.
MiniCPM5 getting-started guide →

05 Gemma-4 family · added Apr 25, 2026

Gemma-4: Google's instruct series.

Two small dense (e2b, e4b), the new 12 B (the unified text+vision Gemma-4, now with image input), and two large (31 B dense, 26 B-A4B sparse-MoE). Mixed-precision recovery is large here, gemma-4-e4b posts a +13.6-point Capability Score gain over uniform 4-bit, and the 12 B adds +6.4. Pair e4b or 31B with their matching -assistant-bf16 drafter for speculative decoding. All five also take image input through a bf16 vision sidecar; see the vision guide.

Capability Score · 6-benchmark mean (MMLU + GSM8K + IFEval + BFCL + HumanEval + HashHop)
Model bf16 size mlx-optiq size Compression Capability Score Δ vs uniform-4
gemma-4-31B-it-OptiQ-4bit 63.5 GB 21.3 GB 3.0× 82.77 +3.29
gemma-4-26B-A4B-it-OptiQ-4bit 53.2 GB 16.8 GB 3.2× 75.76 +2.81
gemma-4-12B-it-OptiQ-4bit 22.8 GB 8.4 GB 2.7× 68.23 +6.40
gemma-4-e4b-it-OptiQ-4bit 14.3 GB 6.2 GB 2.3× 68.92 +13.72
gemma-4-e2b-it-OptiQ-4bit 9.2 GB 4.1 GB 2.2× 56.38 +1.96
QAT variants · OptiQ on Google's quantization-aware-trained bases

Google also publishes QAT-unquantized Gemma-4 checkpoints, bf16 weights tuned so that 4-bit quantization is near-lossless. OptiQ runs its per-layer sensitivity pass on those bases and still beats a uniform 4-bit quant of the same QAT base, by +0.2 to +2.1 Capability points: the mixed-precision allocation keeps finding headroom even after QAT has hardened the weights. The 31B model gains the most in absolute terms (+1.65, driven by a +9-point jump on long-context retrieval). Each scores against a genuine uniform-4 quant of its own QAT base, holding the base fixed.

Model (QAT base) bf16 size mlx-optiq size Compression Capability Score Δ vs uniform-4
gemma-4-31B-it-qat-OptiQ-4bit 63.5 GB 22.4 GB 2.8× 82.01 +1.65
gemma-4-26B-A4B-it-qat-OptiQ-4bit 53.2 GB 20.7 GB 2.6× 74.40 +0.19
gemma-4-12B-it-qat-OptiQ-4bit 22.8 GB 8.9 GB 2.6× 69.64 +1.37
gemma-4-e4b-it-qat-OptiQ-4bit 14.3 GB 6.5 GB 2.2× 68.67 +1.19
gemma-4-e2b-it-qat-OptiQ-4bit 9.2 GB 4.3 GB 2.2× 57.23 +2.09
Mixed-precision KV on Gemma-4 Each Gemma-4 repo above ships a recommended kv_config.json from a real sensitivity-analysis pass. Point optiq serve --kv-config kv_config.json at it. The runtime fills in for upstream mlx-lm's RotatingKVCache.to_quantized (which raises NotImplementedError) via optiq.runtime.kv.RotatingQuantizedKVCache, plus a small SDPA dispatch patch for Gemma-4's KV-sharing layers. The model still loads fine without the config (stock fp16 KV).
Gemma-4 getting-started guide →

06 Qwen3.6 family · added earlier in April 2026

Qwen3.6: strong reasoning.

Qwen3.6 in two configurations: a dense 27 B and a 256-expert MoE with 3 B active per token. Both quantized with the same mlx-optiq pass; both ship a bundled MTP head for ~1.4× decode via optiq serve --mtp. Both beat uniform 4-bit on the six-metric Capability Score, and both take image input via a bf16 vision sidecar (vision guide).

Capability Score · 6-benchmark mean (MMLU + GSM8K + IFEval + BFCL + HumanEval + HashHop)
Model bf16 size mlx-optiq size Compression Capability Score Δ vs uniform-4
Qwen3.6-35B-A3B-OptiQ-4bit 73.7 GB 22.7 GB 3.3× 80.03 +1.28
Qwen3.6-27B-OptiQ-4bit 57.3 GB 17.9 GB 3.2× 86.04 +0.46
Qwen3.6 getting-started guide →

07 Qwen3.5 family · the founding lineup

Qwen3.5: the daily-driver series.

From 0.8 B for prompt-rewriters and toy agents up to 27 B for serious reasoning, plus a 35 B-A3B sparse MoE. All quantized with the same mlx-optiq pass; all ship a bundled MTP head for speculative decoding via optiq serve --mtp; all beat uniform 4-bit on the six-metric Capability Score. Every Qwen3.5 size also takes image input via a bf16 vision sidecar (vision guide).

Capability Score · 6-benchmark mean (MMLU + GSM8K + IFEval + BFCL + HumanEval + HashHop)
Model bf16 size mlx-optiq size Compression Capability Score Δ vs uniform-4
Qwen3.5-35B-A3B-OptiQ-4bit 73.7 GB 21.6 GB 3.4× 77.42 +0.50
Qwen3.5-27B-OptiQ-4bit 57.3 GB 17.8 GB 3.2× 82.22 +0.17
Qwen3.5-9B-OptiQ-4bit 18.4 GB 6.8 GB 2.7× 69.85 +0.19
Qwen3.5-4B-OptiQ-4bit 8.2 GB 3.1 GB 2.6× 68.76 +1.90
Qwen3.5-2B-OptiQ-4bit 3.1 GB 1.5 GB 2.1× 50.41 +2.54
Qwen3.5-0.8B-OptiQ-4bit 1.2 GB 620 MB 2.0× 38.42 +5.44
Recommended starting point For most users on a 36 GB Mac, the Qwen3.5-9B quant is the default. Strongest Capability-per-GB and runs at full 64 k context with mixed-precision KV. Bundled MTP head delivers ~1.4× decode via optiq serve --mtp. Drop to 4 B for laptops with less RAM, step up to 27 B if you have headroom.
The 122B, streamed off SSD The series tops out at Qwen3.5-122B-A10B. Its OptiQ quant is a 2-bit static build (44 GB) that runs on a 36 GB Mac by streaming the mixture-of-experts off SSD: about 12 GB resident, ~5 tok/s. There is no Capability Score for it: at 2-bit that number is not meaningful, so it ships with a coherence check instead: it still writes working code at 2-bit. Read the write-up →
Qwen3.5 getting-started guide →

05 Loading any of them

The same snippet loads any model on this page.

Every OptiQ quant follows the same load contract. Swap the repo name; the rest stays.

load_any.pypython
from mlx_lm import load, generate

# Pick any of the 12. Stock mlx-lm, no special loader needed.
model, tok = load("mlx-community/Qwen3.6-27B-OptiQ-4bit")

prompt = tok.apply_chat_template(
    [{"role": "user", "content": "Explain mixed-precision quantization in 3 sentences."}],
    tokenize=False,
    add_generation_prompt=True,
)
out = generate(model, tok, prompt=prompt, max_tokens=300)
print(out)
Per-family notes Each model family has slightly different recommended sampling defaults and chat templates. See the MiniCPM5, Qwen3.5, Qwen3.6 and Gemma-4 getting-started guides.