# Getting Started Guide — YOLO26 MLX Build Challenge

**URL:** <https://community.webai.com/t/getting-started-guide-yolo26-mlx-build-challenge/20>\
**Category:** Build Challenges\
**Created:** [May 15, 2026, 5:15pm UTC](https://community.webai.com/t/getting-started-guide-yolo26-mlx-build-challenge/20 "2026-05-15T17:15:46Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![jayatwebai](https://yyz2.discourse-cdn.com/flex056/user_avatar/community.webai.com/jayatwebai/32/6_2.png) [@jayatwebai](https://community.webai.com/u/jayatwebai)\
**Post date:** [May 15, 2026, 5:15pm UTC](https://community.webai.com/t/getting-started-guide-yolo26-mlx-build-challenge/20/1 "2026-05-15T17:15:46Z")

</div>

## **Getting Started with YOLO26 MLX**

A 10-minute guide to get YOLO26 MLX running on your Mac.

### **What is YOLO26 MLX?**

YOLO26 MLX is webAI’s pure MLX implementation of YOLO26 for Apple Silicon. It runs entirely on-device with Metal GPU acceleration. No PyTorch dependency at runtime, no cloud calls, no waiting on someone else’s API.

The repo: [github.com/thewebAI/yolo-mlx](https://github.com/thewebAI/yolo-mlx)

### **Requirements**

- Apple Silicon Mac (M1, M2, M3, or M4)
- macOS recent enough to support MLX (14.0+ recommended)
- Python 3.10 or newer
- ~2GB of free disk space for models and dependencies

If you’re on an Intel Mac, this won’t work. The whole point of MLX is Apple Silicon native acceleration.

### **5-minute setup**

Clone the repo, create a virtual environment, install the package, and download a model.

```auto
git clone https://github.com/thewebAI/yolo-mlx.git
cd yolo-mlx
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
pip install -e ".[convert]"

```

Download a pretrained model and convert it to MLX format. We recommend starting with `yolo26n` (the smallest model, ~170 FPS on M4 Pro) for fast iteration:

```auto
bash scripts/download_yolo26_models.sh
yolo26 converters convert models/yolo26n.pt -o models/yolo26n.npz --verify

```

You now have a working MLX model at `models/yolo26n.npz`.

### **Run your first detection**

Grab a sample image and run inference:

```auto
mkdir -p images
curl -L -o images/bus.jpg https://ultralytics.com/images/bus.jpg

```

Then in Python:

```auto
from yolo26mlx import YOLO

model = YOLO("models/yolo26n.npz")
results = model.predict("images/bus.jpg", conf=0.25)
print(results[0])
results[0].save()

```

The output image with bounding boxes will save to the `results/` directory. That’s your hello world.

### **Running on your webcam**

Most builds for this challenge will use live camera input. Here’s a minimal webcam loop:

```auto
import cv2
from yolo26mlx import YOLO

model = YOLO("models/yolo26n.npz")
cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break

    results = model.predict(frame, conf=0.25)
    annotated = results[0].plot()

    cv2.imshow("YOLO26 MLX", annotated)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

```

You’ll need `opencv-python` installed: `pip install opencv-python`.

The first time you run this, macOS will ask for camera permission for your terminal or IDE. Grant it. If you skip the prompt by accident, go to System Settings → Privacy & Security → Camera and enable it for whatever app is running Python.

### **Model size vs. speed**

Five models, pick what fits your use case:

- **yolo26n:** 40.2% mAP, 170 FPS on M4 Pro. Real-time, low-latency demos.
- **yolo26s:** 47.6% mAP, 105 FPS on M4 Pro. Balanced default.
- **yolo26m:** 52.3% mAP, 55 FPS on M4 Pro. Higher accuracy, still fast.
- **yolo26l:** 53.9% mAP, 44 FPS on M4 Pro. Accuracy over speed.
- **yolo26x:** 56.7% mAP, 24 FPS on M4 Pro. Max accuracy, slower.

For most challenge demos, `yolo26n` or `yolo26s` will be the right call. Real-time webcam apps almost always want `n`.

### **Common gotchas**

**MLX won’t install or import.** Make sure you’re on Apple Silicon. `python3 -c "import platform; print(platform.processor())"` should return `arm`. If it returns `i386`, you’re on Intel and this won’t work.

**Camera permission isn’t granted.** macOS blocks camera access by default. The first time your Python script accesses the camera, you’ll get a system prompt. Approve it. If you missed it, go to System Settings → Privacy & Security → Camera and toggle on the app you’re using.

**Model conversion fails.** The `yolo26 converters convert` step needs the `[convert]` extras installed. If you skipped `pip install -e ".[convert]"`, go back and run it.

**Inference is slow.** Make sure you convert the `.pt` weights to `.npz`. If you’re running inference on the raw `.pt` file you’re using PyTorch under the hood, not MLX. The `.npz` is the MLX-native format.

**Out of memory on large models.** `yolo26x` needs more memory than `yolo26n`. If you’re on an 8GB M1, stick with `n` or `s`.

### **Want to fine-tune?**

YOLO26 MLX supports full training and fine-tuning on Apple Silicon. See the [training guide](https://github.com/thewebAI/yolo-mlx/blob/main/GUIDE_TRAINING_BENCHMARK.md) in the repo. For most 7-day challenge submissions, pretrained inference is enough. Fine-tuning is a heavier lift.

### **License note**

YOLO26 MLX is licensed under [AGPL-3.0](https://github.com/thewebAI/yolo-mlx/blob/main/LICENSE). What this means for the challenge: you can absolutely use it, fork it, modify it, and submit it. If you ever plan to deploy your build as a hosted service or web app for real users, AGPL requires you to publish your source code under the same license. For demos, prototypes, and challenge submissions, this isn’t something to worry about.

### **Where to ask questions**

If you’re stuck, head to the [Q&A topic for this challenge](https://community.webai.com/t/q-a-yolo26-mlx-build-challenge/17). Our AI/ML team is watching the threads and will help unblock you.

Happy building.