Installation

mlx-optiq is a pure-Python package on PyPI and needs Python 3.11+. Quantizing and local inference need Apple Silicon, because MLX is an Apple framework. The coding agent and the Lab run on Linux and Windows too, pointed at any OpenAI-compatible endpoint. See Windows and Linux.

One-line install

$ pip install mlx-optiq

That's it. The base install pulls in mlx, mlx-lm, huggingface-hub, click and a handful of small utilities. ~80 MB on disk including all dependencies.

What the install gives you

pip install mlx-optiq is the whole product. Every command works out of the box: optiq convert, optiq serve, optiq eval, optiq lora, optiq kv-cache, optiq latency, the optiq code coding agent, and optiq lab, the local web UI. Loading and running any published quant works immediately.

The dev extra

One extra exists, and only for working on OptiQ rather than with it:

# test suite, browser tests, and the benchmark datasets
$ pip install 'mlx-optiq[dev]'

It carries pytest and Playwright, the datasets library that optiq eval uses to pull MMLU/GSM8K/IFEval/HumanEval, and the two test oracles (mlx-vlm, torch) that the vendored vision tower is validated against. Nothing on the convert, serve, or agent path imports any of it.

Verify the install

$ optiq --version
# mlx-optiq, version 0.4.7

$ python -c "import optiq; print(optiq.__version__)"
# 0.4.7

System requirements

What you need depends on what you are doing. Quantizing needs Metal; driving a model over an API does not.

• Python: 3.11 or newer, everywhere. Distro Python is often 3.10 or older — uv, pyenv or conda will get you a newer one without touching the system install.
• Apple Silicon: macOS 14 (Sonoma) or newer, M1 through M5, any tier.
• RAM (local inference): 16 GB for small quants (0.8–4 B), 24 GB for 9 B, 36 GB+ for 27–35 B and fine-tuning.
• Disk: pre-built quants are 0.5–20 GB each.

Windows and Linux

MLX is an Apple framework, so local inference and quantization are Mac-only. The coding agent and the Lab are not: point them at any OpenAI-compatible endpoint and they are ordinary Python. Install the same package and set two variables.

$ pip install mlx-optiq

# any OpenAI-compatible endpoint: a Mac running `optiq serve` on your
# network, vLLM, Ollama, OpenRouter, or a hosted API
$ export OPTIQ_CODE_BASE_URL=http://your-host:8080/v1
$ export OPTIQ_CODE_API_KEY=your-key
$ export OPTIQ_CODE_MODEL=your-model

$ optiq code          # the agent, driving that endpoint
$ optiq lab           # the web UI, same idea

Every setting has an OPTIQ_CODE_<NAME> variable, or you can put them in ~/.optiq/code/config.json. optiq code config prints each value and where it came from.

Install a container runtime for the sandbox

The Lab's python and terminal tools run code the model wrote. On macOS the OS provides sandbox-exec, which denies network access and confines writes to a scratch directory. Linux and Windows have no equivalent, so there OptiQ uses a container instead, and without one it falls back to running the code as you, in a temp directory.

Install Docker or Podman and the strongest tier turns on by itself. Nothing to configure.

On that last row the AST checks and the blocked-command list are the only thing left, and they are not a sandbox. Treat it as running the model's code with your own permissions, because that is what it is. The Lab shows the active tier so you can tell which row you are on.

Two details specific to Windows. The terminal tool emits sh one-liners, so a container runtime (or Git Bash, or WSL) is what makes it work at all; without one it says so instead of failing strangely. And on macOS, Docker is not preferred over sandbox-exec, because sandbox-exec is already strong there and starts instantly while Docker boots a Linux VM per call.

OPTIQ_SANDBOX_CONTAINER=0 turns the container tier off; naming a runtime, as in OPTIQ_SANDBOX_CONTAINER=podman, forces that one.

Working in a virtualenv

Strongly recommended. uv is the fastest path:

$ uv venv .venv
$ source .venv/bin/activate
$ uv pip install mlx-optiq

Or stock venv:

$ python3.11 -m venv .venv
$ source .venv/bin/activate
$ pip install mlx-optiq

Upgrade

$ pip install --upgrade mlx-optiq

Troubleshooting

"No matching distribution found"

You're probably on Linux, Windows, or Intel macOS. mlx-optiq requires Apple Silicon. There's no fundamental reason it couldn't work on Linux too, but it depends on MLX, which is macOS-only.

Slow first model download

Hugging Face downloads can be slow from some regions. Set HF_HUB_ENABLE_HF_TRANSFER=1 and install hf_transfer for ~5× speedups on large models:

$ pip install hf_transfer
$ export HF_HUB_ENABLE_HF_TRANSFER=1

"Metal command-buffer timeout" while quantizing 27 B+

Long Metal kernels can time out on the macOS GPU watchdog. mlx-optiq patches around this internally for the convert path; if you hit it during fine-tuning, lower --max-seq-length. See the fine-tuning guide's training-ceiling map.

Next: pick a model family. Qwen3.5, Qwen3.6, Gemma-4, or jump to Using mlx-optiq quants.