# How LLMFIT Filters MLX Models to Metal‑Only Systems Using Backend Compatibility Checks

> Discover how LLMFIT ensures Metal-only system compatibility for MLX models using backend checks. Learn how it verifies GpuBackend::Metal and unified memory to prevent GPU execution errors.

- Repository: [Alex Jones/llmfit](https://github.com/AlexsJones/llmfit)
- Tags: internals
- Published: 2026-08-21

---

**LLMFIT restricts MLX models to Apple Silicon machines by verifying `GpuBackend::Metal` and `unified_memory == true` in the `backend_compatible` function, preventing incompatible GPU execution attempts.**

The `llmfit-core` crate in the AlexsJones/llmfit repository enforces strict hardware boundaries for MLX models through a targeted backend compatibility check. This system ensures that models tagged with the MLX suffix only appear as viable options on Metal-enabled Apple Silicon devices, automatically filtering them out on NVIDIA, AMD, or Intel GPU systems.

## How the Backend Compatibility Check Works

The core filtering logic resides in [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs) within the `backend_compatible` function (lines 57-62). This gatekeeper evaluates each model against the detected system capabilities before allowing it into the active model list.

### Identifying MLX Model Types

First, the system identifies MLX-capable models using `LlmModel::is_mlx_model()` defined in [`llmfit-core/src/models.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/models.rs) (lines 221-227). This method detects models bearing the `-MLX-` suffix in their names, distinguishing them from pre-quantized or generic GPU formats.

### Enforcing Metal and Unified Memory Requirements

For any model flagged as MLX, `backend_compatible` returns `true` only when two specific hardware conditions are met simultaneously:

- `system.backend == GpuBackend::Metal`
- `system.unified_memory == true`

These criteria map directly to Apple Silicon architecture, which implements unified memory and utilizes the Metal GPU backend. The [`hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/hardware.rs) module defines these system specifications, capturing the `GpuBackend` enum and memory architecture flags.

### Excluding Special Runtime Models

The compatibility check also immediately excludes special-runtime models such as TTS (Text-to-Speech) implementations before evaluating MLX status. This ensures the hardware-specific filter logic applies only to relevant LLM formats and avoids misclassifying non-standard runtimes.

## Source Code Implementation

The `backend_compatible` function implements this logic in Rust:

```rust
// In llmfit-core/src/fit.rs
use llmfit_core::{
    fit::backend_compatible,
    hardware::{SystemSpecs, GpuBackend},
    models::LlmModel,
};

fn can_run_mlx(model: &LlmModel, specs: &SystemSpecs) -> bool {
    backend_compatible(model, specs)
}

```

When iterating through the model catalog, the CLI calls this function for each entry. MLX models return `false` on non-Metal systems, effectively removing them from the available options.

## CLI Integration and Automatic Filtering

Users interact with this filter through the fit command. The backend compatibility check runs automatically during model enumeration:

```bash

# Display only compatible models (MLX models appear only on Apple Silicon)

cargo run -- fit --perfect

```

This command produces a curated list where MLX models only surface when the host reports Metal backend support and unified memory architecture.

## Why Metal‑Only Filtering Matters

Restricting MLX execution to Metal systems provides three critical advantages:

- **Execution Correctness**: MLX frameworks cannot initialize on CUDA or ROCm devices. The filter prevents runtime failures by blocking incompatible model selection at the compatibility stage.

- **User Experience**: Hiding unavailable models declutters the interface, ensuring users only see benchmarks and options viable on their specific hardware configuration.

- **Resource Efficiency**: By eliminating impossible model fits before benchmarking begins, LLMFIT avoids wasting computational cycles attempting to load Apple-specific tensor formats on non-Apple GPUs.

## Summary

- The `backend_compatible` function in [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs) serves as the primary gatekeeper for model selection.
- MLX identification occurs via `LlmModel::is_mlx_model()` in [`models.rs`](https://github.com/AlexsJones/llmfit/blob/main/models.rs), which checks for the `-MLX-` suffix.
- Metal-only enforcement requires both `GpuBackend::Metal` and `unified_memory == true` to match Apple Silicon specifications.
- The filter automatically excludes MLX options on Linux and Windows systems with NVIDIA or AMD GPUs.
- CLI commands like `fit --perfect` leverage this check to present hardware-appropriate model lists.

## Frequently Asked Questions

### What happens if I try to force an MLX model on a CUDA system?

The `backend_compatible` function returns `false` for MLX models when `system.backend` is not `GpuBackend::Metal`. Even if bypassed at the UI level, the underlying MLX framework would fail to initialize because it requires Metal-specific APIs and unified memory architecture present only on Apple Silicon.

### How does LLMFIT detect if a model uses MLX format?

Detection occurs in [`llmfit-core/src/models.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/models.rs) through the `is_mlx_model()` method, which scans the model name for the `-MLX-` substring (lines 221-227). This naming convention distinguishes MLX tensors from GGUF, GPTQ, or other quantization formats.

### Can MLX models run on Intel Macs with Metal support?

No. While Intel Macs may support Metal, the compatibility check specifically requires `unified_memory == true`. Only Apple Silicon devices (M1, M2, M3, etc.) implement the unified memory architecture that MLX frameworks depend on for tensor operations, making Intel Macs incompatible despite having Metal-capable GPUs.

### Where is the hardware detection logic defined?

System capability detection resides in [`llmfit-core/src/hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs), which defines the `GpuBackend` enum including the `Metal` variant and tracks the `unified_memory` boolean flag. The `backend_compatible` function in [`fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/fit.rs) imports these definitions to perform the actual filtering logic.