Guide · 2026-07-18

How to Build llama.cpp with Metal on Mac M-Series

Last updated 2026-07-18

A no-nonsense 2026 guide to compiling llama.cpp with Metal GPU acceleration on Apple Silicon, plus real throughput numbers across M1–M4 chips.

By Mohamed Meguedmi · 9 min read

Prerequisites: What You Need Before You Build

Building llama.cpp with Metal on an M-series Mac is refreshingly boring — there is no separate GPU driver stack to fight, because Metal ships with macOS and the GPU shares the same unified memory as the CPU. You need exactly three things installed.

• Xcode command-line tools — provides clang, the Metal compiler, and the SDK. Install with xcode-select --install.
• CMake 3.14+ — the current, supported build system. Install with brew install cmake (via Homebrew).
• git — already present if you installed the Xcode tools.

That is the entire dependency list. macOS 13 Ventura or later is recommended so you get the modern Metal 3 feature set; anything on an M1 through M4 chip running macOS 14 or 15 is ideal. If you are still deciding which model to run once the build works, our model catalog and benchmarks hub are the fastest way to size a download against your available RAM.

Build llama.cpp with Metal in Under 5 Minutes

The repository moved to the ggml-org organization, so clone from there rather than the old ggerganov path (the old one still redirects, but use the canonical URL). The build is a two-command CMake flow.

# 1. Clone the current repository
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# 2. Configure (Metal is auto-detected on Apple Silicon)
cmake -B build

# 3. Compile with all cores
cmake --build build --config Release -j

That is it. Because GGML_METAL defaults to ON for arm64 macOS, the configure step compiles the Metal shaders and links against the system Metal and Accelerate frameworks automatically. If you want to be explicit (useful in CI logs), you can pass it by hand:

cmake -B build -DGGML_METAL=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

Your binaries land in build/bin/. The two you will actually use are llama-cli (one-shot and interactive chat) and llama-server (an OpenAI-compatible HTTP endpoint). Run a quick smoke test, offloading all layers to the GPU with -ngl 99:

./build/bin/llama-cli \
  -m ~/models/Llama-3.1-8B-Instruct-Q4_K_M.gguf \
  -ngl 99 \
  -p "Explain unified memory in one sentence."

Do not use bare make. The legacy Makefile was deprecated in August 2024. It may still exist but is unmaintained, produces slower binaries, and misses newer Metal kernels. CMake is the only supported path in 2026.

Verify Metal Is Actually Working

A build can succeed while silently running on the CPU — usually because layers were never offloaded. Check the startup log. When Metal is live you will see lines similar to these near the top of the output:

ggml_metal_init: found device: Apple M4 Max
ggml_metal_init: GPU name:   Apple M4 Max
load_tensors: offloading 32 repeating layers to GPU
load_tensors: offloaded 33/33 layers to GPU

The decisive line is offloaded N/N layers to GPU. If it reads 0/33, you forgot -ngl 99 or ran out of memory. If you see found device naming your chip, the Metal backend compiled correctly. You can also confirm the backend at build time — the CMake configure output prints GGML_METAL: ON.

Benchmark: Token Throughput Across M-Series Chips

The reason to use Metal at all is throughput. On Apple Silicon, token-generation speed is gated almost entirely by memory bandwidth, not raw GPU core count — which is why a Max-tier chip crushes a base chip even at similar clock speeds. The table below shows representative llama.cpp text-generation rates (tokens/second, single stream, all layers offloaded) for two common quantized models. Treat these as ballpark figures; exact numbers vary with macOS version, context length, and the specific build.

Chip	GPU cores	Memory bandwidth	Llama 3.1 8B Q4_K_M	Qwen2.5 32B Q4_K_M
M1 (base)	7–8	68 GB/s	~22 tok/s	too tight (needs 24GB+)
M2 (base)	10	100 GB/s	~28 tok/s	~7 tok/s
M4 (base)	10	120 GB/s	~34 tok/s	~9 tok/s
M1 Max	32	400 GB/s	~45 tok/s	~13 tok/s
M3 Max	40	400 GB/s	~58 tok/s	~16 tok/s
M4 Max	40	546 GB/s	~76 tok/s	~21 tok/s

The pattern is unmistakable: bandwidth scales almost linearly with generation speed. An M4 Max delivers roughly 3.4× the 8B throughput of a base M1 despite a smaller multiple in GPU core count. If you are weighing a hardware purchase against renting cloud inference, our cost calculator converts these token rates into a break-even timeline.

Tuning Flags That Actually Matter on Apple Silicon

Most CUDA and ROCm tuning advice does not apply here — those flags do not even exist in a Metal build. The short list below is what moves the needle on M-series hardware.

Flag	What it does	Recommendation
-ngl 99	Offloads all layers to the Metal GPU	Always set it. Lower only if you are out of RAM.
-c N	Context window size (tokens)	Set to what you need; larger contexts eat unified memory fast.
-fa on	Flash attention	Enable it — lowers memory use and speeds long contexts on Metal.
-t N	CPU threads	Set to your performance core count, not total. More P-cores than you have hurts.
-b / -ub	Batch / micro-batch size	Defaults are fine for chat; raise for bulk prompt processing.

Two anti-patterns to avoid. First, do not oversubscribe threads: setting -t above your P-core count adds contention with no throughput gain. Second, ignore any half-precision CUDA flag you find in cross-platform guides — -DGGML_CUDA_F16 and friends simply are not compiled into a Metal binary.

Common Build Errors and Fixes

"xcrun: error: unable to find utility 'metal'"

Your command-line tools are incomplete or point at a stale path. Reinstall with xcode-select --install, and if you have full Xcode installed, run sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer.

Build succeeds but runs on CPU only

You almost certainly omitted -ngl 99 at runtime, or the model plus context exceeds free unified memory and layers fell back to CPU. Watch the offloaded N/N layers line and reduce context or quantization level if needed.

CMake can't find a compiler

Homebrew installed CMake but the Xcode tools license was never accepted. Run sudo xcodebuild -license accept, then delete build/ and reconfigure.

llama-cpp-python instead of the native binary

If your goal is the Python bindings rather than the CLI, install with the Metal flag exposed: CMAKE_ARGS="-DGGML_METAL=on" pip install -U llama-cpp-python --no-cache-dir. This guide focuses on the native build, which is faster to compile and gives you llama-server directly.

Verdict: The Fastest Path That Works

For anyone on Apple Silicon in 2026, the native CMake build is the right call — it is a five-minute compile with zero driver friction, and Metal acceleration is automatic. Skip the Makefile, skip the manual LLAMA_METAL=1 flag, and always run with -ngl 99. The only real decision left is which chip and how much RAM, because memory bandwidth and capacity dictate everything downstream.

Use case	Recommended setup	Why
Chat + 7–8B models	Any M2/M3/M4, 16 GB	30+ tok/s is comfortable; bandwidth is plenty.
Coding assistants, 14–32B	M3/M4 Max, 48–64 GB	Fits Q4_K_M with headroom for long context.
70B-class experimentation	M4 Max/Ultra, 128 GB	Only high-RAM chips hold the weights at usable speed.
Python-native pipelines	Native build + bindings	Build once, reuse the server API from any client.

Once you are running, note that llama-server exposes an OpenAI-compatible endpoint at http://localhost:8080/v1, so any existing OpenAI client library works unchanged. For deeper hardware and model comparisons, browse the rest of our guides. And if you are building tooling on top of this, the BestLLMfor public API (licensed CC BY 4.0) and our open-source MCP server let you query model specs and benchmark data programmatically — the same numbers behind the tables above.