llama.cpp Flags Explained (2026): Every Flag That Matters

Bottom Line (2026)

• Three flags changed underneath everyone in 2026. --no-mmap, --mlock and --direct-io were folded into -lm, --load-mode (PR #20834, merged 2026-07-23), kept as deprecated aliases, then removed outright in PR #28334. Most command lines published before mid-2026 now fail with error: invalid argument.
• -ngl now defaults to auto. The advice to always pass -ngl 99 is a workaround for a default that no longer exists.
• Separate the memory flags from the speed flags. This is the distinction almost nobody writes down, and it is why people set KV cache quantization expecting a speed-up and measure a slow-down.
• Only two flags reliably buy you speed on a machine that already fits the model: -fa and -ub. Everything else buys you the ability to run the model at all.
• Do not copy a --n-cpu-moe value. Sweep it. See llama.cpp MoE Offload Flags Explained for the method.

The Flag Table

Flag spellings and defaults below are quoted from the llama-server README on 2026-09-15. Check your own build with llama-server --help; this project moves fast.

Memory Flags and Speed Flags Are Not the Same Thing

This is the distinction that makes the table usable.

A memory flag changes whether the model runs at all. -ngl, -c, --cache-type-k, --cache-type-v, --n-cpu-moe, -ts and --swa-full all trade something away so the weights and the cache fit in the memory you own. Most of them make generation slower. You accept that, because the alternative is not running.

A speed flag changes tokens per second on a model that already fits. There are far fewer of these than the internet implies. -fa on is the reliable one. -ub helps prompt processing when you raise it and helps VRAM fit when you lower it. -t matters when the CPU is doing real work, which now includes every MoE offload setup.

The practical consequence: quantizing your KV cache will not speed anything up. --cache-type-k q8_0 is a memory feature. It frees VRAM so you can raise -c, and it adds conversion work on every token. If f16 fits, f16 is faster. People try it as a performance tweak, measure a regression, and conclude llama.cpp is unpredictable. It is not; the flag was never a speed flag.

The 2026 Breaking Change: --no-mmap and --mlock Are Gone

If you have hit error: invalid argument on a command that worked last year, this is almost certainly why.

llama.cpp collapsed four separate loading flags into one. -lm, --load-mode MODE now takes:

The migration table is short:

The honest caveat nobody publishes with the migration table. The new enum treats mlock as always implying mmap, so the old --no-mmap --mlock combination has no replacement. That combination mattered specifically to MoE offload users: it loaded weights into ordinary heap buffers while stopping the kernel swapping out the CPU-resident expert tensors. Issue #26110, opened 2026-07-25 and still open at the time of writing, reports the consequence — -lm none lets CPU-resident weights get swapped out under load, with throughput falling from roughly 25-27 tok/s to 7.55 tok/s, while -lm mlock double-buffers the model and invites the OOM killer.

If you run a large MoE with --n-cpu-moe on a machine that is tight on RAM, test both modes and watch swap. There is currently no setting that gives you what the old pair gave you.

Why Your Copied Command Line Fails

Three failures account for most of them.

1. error: invalid argument: --no-mmap — the flag was removed. Use -lm none.
2. error: invalid argument: --ngl — that is the long form spelled wrong. The short flag is -ngl with one dash; the long forms are --gpu-layers and --n-gpu-layers.
3. error: invalid argument: -cd — -cd is not a llama-server flag. It comes from speculative-decoding examples for other tools in the project. Every binary in llama.cpp has its own argument list, and a flag that exists for one is not guaranteed to exist for another. Check the README for the tool you are running.

The Flags Worth Setting By Hand

Everything defaults sensibly now. These are the ones still worth a deliberate value.

• -c, --ctx-size — the default reads the model’s trained context, which on a modern model can be enormous and will reserve VRAM to match. Set it to the context you actually use. This is the single most common cause of “it used to fit.”
• -fa on — leaving it on auto is fine, but pin it on when you are benchmarking, so a build-to-build change in the auto heuristic does not silently move your numbers.
• -ub — lower it to 256 when you are a few hundred megabytes short of fitting. Raise it when prompt processing is your bottleneck and VRAM is not.
• --n-cpu-moe N — for MoE models only, and only after a sweep.
• -np, --parallel — raise it only if you genuinely serve concurrent requests. Each slot reserves its own KV cache, so raising it on a single-user machine costs VRAM and returns nothing.

How to Find Your Own Numbers

The values in every guide, including this one, came off somebody else’s machine. Quant, RAM speed, context length, GPU and CPU all move them. The method transfers; the numbers do not.

1. Start from defaults. Set only -c to the context you need.
2. Change one flag. Measure tokens per second on a fixed prompt.
3. Watch VRAM while you do it. The cliff where VRAM spills into driver-managed system memory is sharp, and on many systems it produces no error message at all — just a collapse in speed.
4. When speed collapses, back off one step and stop.

Which card you own decides how many of these flags you ever need — most of the memory flags exist to work around VRAM you do not have.

See Also

• llama.cpp MoE Offload Flags Explained — the deep dive on --n-cpu-moe, with measured sweeps
• Why Local LLMs Are Slow Even When They Fit — the bandwidth ceiling no flag can raise
• KV Cache Quantization: q8 vs q4 and VRAM — how much context each cache type buys
• How Much VRAM for 128K Context? — sizing -c before you set it
• IQ4_XS vs Q4_K_M vs Q4_K_XL — picking the quant that fits the VRAM you have
• vLLM vs llama.cpp vs SGLang — when the flags are not the problem and the engine is
• Why Is My Local LLM So Slow? — the diagnostic order to work through first