HOW-TO · SET

How to set up Metal GPU acceleration on macOS

intermediate10 minBy Eruo Fredoline
Target environment
Ubuntu 24.04 · Ollama 0.4.xWindows 11 · Ollama 0.4.xmacOS 15 · Ollama 0.4.x
PREREQUISITES

Mac with Apple Silicon or AMD GPU, macOS 14 Sonoma or later

What this does

Enables the Metal framework as a GPU compute backend on macOS, allowing supported applications and AI runtimes to dispatch compute kernels to the integrated GPU on Apple Silicon. This is required for local model inference frameworks that target the Metal API.

Steps

  1. Check the GPU configuration. This confirms the hardware and driver layer are healthy.

    system_profiler SPDisplaysDataType | grep -A 5 "Chipset Model"

    Expected output: GPU identifier such as Chipset Model: Apple M3 Pro.

  2. Install Xcode Command Line Tools. The Metal compiler headers are included in these tools.

    xcode-select --install

    Expected output: Installation confirmed or "tool already present".

  3. Install PyTorch with MPS support. Use the Metal Performance Shaders backend for GPU compute.

    pip install torch
python3 -c "import torch; print('MPS available:', torch.backends.mps.is_available()); print('MPS built:', torch.backends.mps.is_built())"

    Expected output: MPS available: True / MPS built: True.

  4. Run a small GPU compute operation via Metal.

    python3 -c "
import torch
device = torch.device('mps')
a = torch.randn(2048, 2048, device=device)
b = torch.randn(2048, 2048, device=device)
c = torch.matmul(a, b)
print('Metal compute succeeded, result shape:', c.shape)
"

    Expected output: Metal compute succeeded, result shape: torch.Size([2048, 2048]).

Verification

system_profiler SPDisplaysDataType 2>/dev/null | grep "Metal" | head -1
# Expected: Metal: Supported

Common failures

  • MPS available: False on Apple Silicon — macOS may be older than 14.0. Update via System Settings > General > Software Update.
  • MPS not supported for this build — CPU-only PyTorch variant installed. Use pip install --upgrade torch for the universal2 build.
  • Metal not shown as supported — Driver-level issue. Reinstall macOS updates.
  • Segmentation fault on matmul with large tensors — MPS has alignment constraints on buffers exceeding 2 GB. Reduce tensor size.
  • xcode-select: command not found — Command Line Tools are missing. Run xcode-select --install with GUI prompt.
  • Model inference slower than expected on MPS — Some operations fall back to CPU. Set environment variable PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0 to force full GPU offload.

Related guides

RELATED GUIDES
SET
How to configure PyTorch with GPU support
← All how-to guidesCourses →