Optional install extras

A bare pip install rapid-mlx==0.10.3 is enough to serve any text model. The optional extras below unlock specific capabilities — vision, MTP speculative decoding, embeddings, audio, dev tooling — without paying their disk cost by default.

How to install an extra

Bracket syntax; quote for zsh:

$ pip install "rapid-mlx[vision]==0.10.3"
$ pip install "rapid-mlx[vision,mtp]==0.10.3"    # combine
$ pip install "rapid-mlx[all]==0.10.3"           # vision + chat + embeddings

User-facing extras

[vision] — multimodal models (Gemma 4, Qwen VL, etc.)

Adds roughly 322 MB of dependencies. Required for any model with vision input; text-only models work without this.

• mlx-vlm>=0.6.3 — DiffusionGemma + Gemma 4 unified path; also unlocks DFlash spec-decode hooks.
• opencv-python>=4.8.0
• torch>=2.3.0
• torchvision>=0.18.0
• pillow>=10.0.0

$ pip install "rapid-mlx[vision]==0.10.3"

[mtp] — MTP speculative decoding (Gemma 4 external assistant path)

Adds the sidecar-path dependency for --spec-decode mtp --mtp-sidecar <path>. The assistant-drafter loader transitively imports mlx_lm.utils → transformers, which reaches for PIL when the sidecar checkpoint has an image-processor preprocessor_config.json. Without PIL on PYTHONPATH, boot fails with a misleading ModuleNotFoundError: No module named 'PIL'.

• pillow>=10.0.0

$ pip install "rapid-mlx[mtp]==0.10.3"

For Gemma 4 targets specifically (as opposed to just MTP wiring), also install [vision] — the Gemma 4 text-target constructor surfaces its own actionable ImportError with a size-tiered install hint. Combine as rapid-mlx[mtp,vision]==0.10.3.

Homebrew note. The Homebrew formula does not auto-install [mtp]. On Homebrew installs, add pillow>=10.0.0 manually into /opt/homebrew/Cellar/rapid-mlx/<v>/libexec or run rapid-mlx from a pip venv where you can pass the extra directly.

[dflash] — DFlash speculative decoding for Qwen 3.5/3.6 dense 8bit

Adds ~1-4 GB at runtime (drafter weights) and depends on mlx-vlm's spec-decode runtime. Text-only — does not pull torch / cv2 like [vision]. Only enable if you serve a DFlash-eligible alias (e.g. qwen3.5-27b-8bit) with --enable-dflash.

• mlx-vlm>=0.6.3

$ pip install "rapid-mlx[dflash]==0.10.3"

[embeddings] — /v1/embeddings endpoint

Unlocks --embedding-model at serve time. Required to preload an embedding model like mlx-community/embeddinggemma-300m-6bit.

• mlx-embeddings>=0.1.0

$ pip install "rapid-mlx[embeddings]==0.10.3"

[chat] — Gradio chat UI

Adds the rapid-mlx-chat Gradio front-end (separate from the REPL you get from rapid-mlx chat).

• gradio>=4.0.0
• pytz>=2024.1

$ pip install "rapid-mlx[chat]==0.10.3"

[audio] — TTS and STT (kokoro, whisper, parakeet, vibevoice, voxcpm, chatterbox, dia)

Every audio alias (see the audio registry) needs this extra. Ships upper-cap pins the audio surface has actually been dogfooded against — notably mlx-audio is pinned <0.4.4 because 0.4.4 regressed Kokoro's istftnet so every Kokoro request 500s.

• mlx-audio>=0.2.9,<0.4.4
• sounddevice>=0.4.0, soundfile>=0.12.0
• scipy>=1.10.0, numba>=0.57.0
• tiktoken>=0.5.0
• misaki[zh,ja]>=0.5.0, spacy>=3.7.0, num2words>=0.5.0, loguru>=0.7.0
• espeakng-loader>=0.2.0, phonemizer-fork>=3.3.0 (fork, not vanilla — see below)
• Chinese: ordered_set>=4.1.0, cn2an>=0.5.0, jieba>=0.42.0
• Japanese: fugashi>=1.3.0, unidic-lite>=1.0.0

Kokoro imports misaki.espeak which calls EspeakWrapper.set_data_path(...) — the legacy 3.2-era API. Vanilla phonemizer>=3.3.0 removed it in favour of a property-only data_path accessor, so phonemizer-fork is required (not just preferred).

$ pip install "rapid-mlx[audio]==0.10.3"

[guided] — outlines-based structured JSON output

Enables guided decoding for schemas.

• outlines[mlxlm]>=1.0.0

$ pip install "rapid-mlx[guided]==0.10.3"

[all] — vision + chat + embeddings union

One-shot install of the three user-facing runtime extras. Expanded inline (not rapid-mlx[vision,chat,embeddings]) to avoid the self-dependency pitfall that breaks editable installs.

$ pip install "rapid-mlx[all]==0.10.3"

Note: [all] does not include [audio], [mtp], [dflash], [guided], [vllm], [test], or [dev] — add those explicitly if you need them.

Contributor / test extras

[test] — minimum pytest runtime

What pytest tests/ needs to import + collect every test cleanly. Kept narrow on purpose so pr_validate can rebuild a venv without the linter toolchain.

• pytest>=7.0.0
• pytest-asyncio>=0.21.0 — required because pytest.ini sets asyncio_mode = auto.
• prometheus_client>=0.16.0 — parses /metrics output through the official parser.
• tomli>=2.0.1 (Python < 3.11 only) — for the L-07 vision-extra lock-in tests.
• aiohttp>=3.9.0, pillow>=10.0.0
• Darwin-only: mlx-vlm>=0.6.3, mlx-audio>=0.2.9,<0.4.4

$ pip install "rapid-mlx[test]==0.10.3"

[dev] — test runtime + linters + type-checker

Mirrors [test] and adds Black, Ruff, mypy. A unit test in tests/test_pr_validate_test_env.py asserts every [test] dep is also in [dev] so a future drift can't silently break the "install dev, run pytest" workflow.

• Everything in [test]
• black>=23.0.0, ruff>=0.1.0, mypy>=1.0.0

$ pip install "rapid-mlx[dev]==0.10.3"

[vllm] — vLLM plugin path

Registers rapid-mlx as a vLLM platform plugin.

• vllm>=0.4.0

$ pip install "rapid-mlx[vllm]==0.10.3"

Verify what's installed

rapid-mlx doctor surfaces each optional extra's status:

◆ Optional Packages
  ⚠ mlx-vlm (vision extras) not installed (`pip install 'rapid-mlx[vision]'`)
  ⚠ mlx-audio (audio extras) not installed (`pip install 'rapid-mlx[audio]'`)
  ⚠ mlx-embeddings (embeddings extras) not installed (`pip install 'rapid-mlx[embeddings]'`)
  ⚠ mlx-vlm 0.5.0+ (dflash extras) not installed or too old

Next steps