---
title: MLX Model Explorer
emoji: 🧭
colorFrom: gray
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Find the right MLX model and quantization for your Mac
tags:
  - mlx
  - apple-silicon
  - quantization
---

# MLX Model Explorer

Explore MLX models and quantizations for your Mac. Compare `mlx-community` models by memory, quantization, popularity and community experience. You can also contribute anonymous hardware and benchmark data to improve recommendations for everyone.

**The question it answers:** given my Mac, model family, size, context length and trade-off, which MLX model and quantization should I use?

## What it does

- Lists every model in [`mlx-community`](https://huggingface.co/mlx-community), refreshed from the Hub every 6 hours. Filter by family, size, quantization and context.
- Estimates memory for each model: exact weight file sizes plus the KV cache at your context (read from `config.json`) plus runtime overhead. It then rates the fit against the GPU-usable memory of your Mac as Comfortable, Likely, Borderline or Unlikely.
- Ranks results with a transparent score (hardware fit, quantization vs. your priority, context headroom, downloads and likes, recency, community data). Every result explains its score. The score never looks at who uploaded a model or what it is called.
- Offers an optional **browser hardware estimate** (WebGPU). This is *not* an MLX benchmark; browsers can't run MLX or read unified memory size.
- Provides an optional **real MLX benchmark** script (`bench/mlx_explorer_bench.py`) you run on your Mac with `mlx-lm`, and optional "how did it work?" reports.
- Publishes anonymous event data to [`mlx-community/mlx-model-explorer-data`](https://huggingface.co/datasets/mlx-community/mlx-model-explorer-data), plus aggregate stats at `/stats`.

## Privacy

No login, cookies, IP addresses, user-agent strings or fingerprints are stored. A random per-tab session ID counts sessions and is discarded when the tab closes. Browsers sending Global Privacy Control or Do Not Track send nothing unless the user opts in, and anyone can opt out on the page. Aggregates with fewer than 5 events are folded into "other". See the dataset card for the full schema.

## Architecture

```
static/      index.html, app.js (UI + batched anonymous events), webgpu.js (browser estimate), stats page
app/         FastAPI
  catalogue.py      mlx-community listing, 6h refresh, disk cache + bundled snapshot fallback
  parsing.py        family / size / quantization / architecture from tags, config.json and names
  model_detail.py   lazy config.json + file sizes per model (cached, parallel, timeout-bounded)
  memory.py         weights + KV cache + overhead, GPU-usable memory, fit classes
  recommend.py      RecommendationEngine interface + HeuristicEngine v1
  events.py         strict event schema, bounds, note scrubbing, plausibility flags
  sink.py           buffered Parquet shards into data/incoming: local directory (dev) or Hub dataset (prod)
  stats.py          k-anonymous aggregates (one count per visit) + per-model community signals
bench/       mlx_explorer_bench.py (runs locally with mlx-lm; submits only with --submit)
data/        catalogue_snapshot.json.gz (fallback when the Hub API is unreachable)
scripts/     deploy.py (create/upload/publish), compact.py (monthly compaction)
tests/       pytest suite
```

The page records **one summary row per visit** (final filters, what was searched, hardware class, models opened/compared/visited) plus explicit contributions (feedback, MLX and browser benchmarks). Individual clicks are never logged. The Space buffers rows and writes one Parquet shard to `data/incoming/YYYY/MM/DD/` at most hourly, or sooner after 2,000 rows. A failed upload stays spooled on disk and retries with backoff. Once a month, `scripts/compact.py` merges the previous month into `data/events/YYYY-MM.parquet` (see DEPLOY.md).

## Configuration

| Env var | Default | Meaning |
| --- | --- | --- |
| `EXPLORER_SINK` | `local` | `hub` (write to the dataset), `local` (write Parquet under `EXPLORER_DATA_DIR`), `off` (collect nothing) |
| `DATASET_REPO` | `mlx-community/mlx-model-explorer-data` | dataset for `hub` mode |
| `HF_TOKEN` | (none) | **Space secret**, a fine-grained token with write access to the dataset only. It is never used for catalogue requests |
| `HF_READ_TOKEN` | (none) | optional token for Hub reads (rate limits only) |
| `EXPLORER_FLUSH_SECONDS` | `3600` | maximum time between writes |
| `EXPLORER_FLUSH_ROWS` | `2000` | write early once this many rows are buffered |
| `EXPLORER_DATA_PREFIX` | `data/incoming` | where the Space writes shards |
| `EXPLORER_ORGS` | `mlx-community` | organizations to list |
| `EXPLORER_RATE_PER_MIN` | `120` | event requests per client per minute |

## Develop and test locally

```bash
uv venv .venv --python 3.12 && uv pip install --python .venv/bin/python -r requirements.txt pytest
.venv/bin/python -m pytest                        # unit + API tests
EXPLORER_SINK=local .venv/bin/uvicorn app.main:app --port 7860
open http://localhost:7860                        # events land in .runtime/local_dataset/

docker build -t mlx-model-explorer . && docker run --rm -p 7860:7860 -e EXPLORER_SINK=local mlx-model-explorer
```

## Deploy

See [DEPLOY.md](DEPLOY.md). The Space and dataset are created **private**, tested end to end, and only made public once reviewed.