Install KoboldCpp on a Mac with Apple Silicon

Apple Silicon only (and what Intel Mac owners can do)

Upstream says Intel Macs build from source. Your options:

• Build from source. Users report CPU only: build from source.
• Run it on another PC and open it from the Mac’s browser: remote access.
• Colab: Colab.

To check your chip, open the Apple menu, then About This Mac. A chip line that names an M-series chip means Apple Silicon; “Intel” means it does not.

KoboldCpp Mac: Step 1, download

Download koboldcpp-mac-arm64 from the official release, or use the download picker. We have not checked what Safari does to the file name; third-party pages list wrong names such as koboldcpp_mac, so use the exact name above.

Step 2: Make it executable

Browsers do not keep the executable bit. In Terminal, change to the folder (or move the file to one first) and run:

$ cd ~/Downloads
$ chmod +x koboldcpp-mac-arm64

If you see zsh: permission denied, this step was skipped.

Step 3: Get past Gatekeeper

The file is signed only ad hoc, with no developer ID and no notarization, and macOS’s own check (spctl --assess) printed rejected for it in our test F106, so macOS may refuse to open it the first time. We could not show the prompt (no screen), so we cannot quote the exact wording on the current macOS release. The README points to Apple’s own instructions. In outline:

1. Run ./koboldcpp-mac-arm64 once and let macOS block it.
2. Open System Settings, then Privacy & Security, scroll to the Security section and choose Open Anyway for this file.
3. Confirm, and enter your password if asked.

Users also report removing the quarantine attribute with the xattr command (#24). On our test Mac, started from a shell, --version ran with the quarantine attribute set and also without it, so a terminal launch was not blocked either way; whether Finder blocks it we could not test F106.

Step 4: Launcher or Terminal

Run the file with no arguments to open the launcher (launcher), or give a model for a server start:

$ ./koboldcpp-mac-arm64
$ ./koboldcpp-mac-arm64 --model ~/models/model.gguf

Users report a broken launcher window on macOS in some cases (#834); the Terminal start is the fallback. A saved .kcpps config loaded the same settings on macOS in our test F08. On a macOS virtual machine, a tiny model was ready in 5.2 to 6.6 s F04; that is a VM number, not a Mac number. Defaults: context 16384, GPU layers automatic F05.

Step 5: Check Metal is used

The log shows MTL0 buffers when the GPU is used. In our virtual machine we saw them F29. On a second run (macOS 15.8.2, an M1 virtual machine with 7.5 GB) the log said it found no default.metallib and loaded the kernel sources instead, and the Metal tensor API was off for older chips: both appeared in a start that otherwise worked F102. Our config and load checks gave the same results on this Mac as on Linux (config files, model won’t load). Full GPU offload has been the macOS default since 1.74 (upstream release notes). A Metal-free failsafe library has shipped since 1.116 for Macs where Metal fails: use --failsafe or --usecpu then. See not using the GPU.

How big a model fits your Mac

A Mac shares one pool of memory between the CPU and the GPU (“unified memory”). macOS lets the GPU use only part of it by default; users report about 65 to 75% (#24). We have not measured the limit on a real Mac. So the sizes below are estimates, not measured values:

For an 8B model at Q4_K_M we measured the real allocations on a software GPU: about 5.1 GiB at 8K context and 8.1 GiB at 32K, so a 16 GB Mac has room for 8K but is tight at 32K (out of memory). See models, quantization and context size.

Update and uninstall

Replace the file, then repeat chmod +x and the Gatekeeper step for the new file (we have not tested whether a replaced file needs approval again). To uninstall, delete the binary, your models and your .kcpps files. We have not recorded where the temporary unpack folder is on macOS.

If it doesn’t start