# Port Model to MLX-VLM

Ports a new model architecture into MLX-VLM with config, weights and tests.

- Repository: https://github.com/Blaizzy/mlx-vlm (5707 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Blaizzy/mlx-vlm --skill add-new-model -g -a claude-code -y`
Codex: `npx skills add Blaizzy/mlx-vlm --skill add-new-model -g -a codex -y`
Cursor: `npx skills add Blaizzy/mlx-vlm --skill add-new-model -g -a cursor -y`
Gemini CLI: `npx skills add Blaizzy/mlx-vlm --skill add-new-model -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Blaizzy/mlx-vlm`

## Description

Use this skill when the user wants to add or port a new model architecture to MLX-VLM, mapping a Hugging Face model_type to a new file under mlx_vlm/models, writing the ModelConfig, matching layer/weight names, reusing a similar existing model, adding a test class, and validating the port. Covers vision-language, language, audio, and diffusion model ports.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Add a New Model

Use this workflow to port a new model to MLX-VLM.

## Layout Rules

- New model lives in `mlx_vlm/models/<model_type>/`, and the main file is named after the `config.json` `model_type` (e.g. `model_type: "llava"` → `mlx_vlm/models/llava/llava.py`). The loader resolves the arch by importing `mlx_vlm.models.<model_type>` (see `MODEL_REMAPPING` in `mlx_vlm/utils.py` for aliases).
- Split by concern like the existing families: `language.py`, `vision.py`, `config.py`, `processing_*.py`. A new kernel/helper goes in **its own file** in the model dir, not inside `language.py`.
- **Start from a similar existing model** in `mlx_vlm/models/` and adapt, don't write from scratch.

## Steps

The rest: https://github.com/Blaizzy/mlx-vlm/blob/HEAD/skills/skills/add-new-model/SKILL.md