Back to all posts

llama.cpp Reaches 1.0: The Contract Matters More Than the Features

2026-11-15
luodaInt
llama.cpp Reaches 1.0: The Contract Matters More Than the Features

llama.cpp Reaches 1.0: The Contract Matters More Than the Features

On 13 November 2026 the ggml-org team released llama.cpp v1.0.0 and ggml v1.0.0 together. The release notes are long and full of things a local-model product would want: FP8 KV caches, a host-memory MoE expert cache, new model architectures, a text-to-speech endpoint, a rebuilt web UI.

The part worth reading twice is the smallest section on the page. Both libraries now follow semantic versioning, and the team has written down what that means for the public C API.

That is a change in the kind of dependency llama.cpp is, not just in its feature list. For anyone who wraps the library or ships it inside a product, a version contract is the thing you build maintenance policy on. And a 1.0 release is where a project usually charges for the contract by removing the escape hatches it had been carrying.

What the version number now means

The rules in the announcement are short enough to quote as a table:

| Change type | Version bump | | --- | --- | | Breaking change to the public C API in ./include | MAJOR | | Backward-compatible feature, backend update, model support, or API addition | MINOR | | Bug fix with no API change | PATCH |

The announcement states that both llama.cpp and ggml "will reflect API and ABI incompatibilities with major-version bumps," and that the team intends to be "stricter about making those boundaries visible to downstream consumers" as adoption grows.

Two details in the announcement define the scope, and both matter more than they look:

  • The promise covers the public C API in ./include. For llama.cpp that is the libllama headers, for ggml the libggml headers.
  • The promise is about the library. It does not say anything about the HTTP API of llama-server, the command-line flags, or the behaviour of the bundled tools.

If you compile against the headers, you now have a stated rule for when your build can break. If you only talk to llama-server over HTTP, you have a different integration surface, and the version number says less about it. That distinction is the practical heart of this release.

The 1.0 release pays for the promise immediately

A versioning contract is only credible if the project is willing to spend a breaking change at a major bump. This release does exactly that.

According to the release notes, llama.h removes llama_set_warmup, 35 deprecated functions, the defrag_thold field and the --defrag-thold flag (pull request #30565). It also promotes the NextN API out of llama-ext.h and renames llama_set_embd_state_src to llama_set_ctx_state_src.

The same pattern runs through the rest of the stack. clip.h is removed and the model and subcontext infrastructure is consolidated into mtmd (pull request #31865). ggml 1.0.0 prunes its deprecated public API and the legacy DIAG_MASK operations, and bumps the RPC protocol to v9, which the notes describe as rejecting incompatible peers.

For a wrapper library this is a real afternoon of work: renamed symbols, a header that moved, and a list of functions that no longer exist. For a team that only runs the server binary, none of it applies directly, which is why the two audiences need separate upgrade checklists. The RPC bump adds a third: if you split inference across machines with ggml RPC, both ends have to move together.

The sequencing is deliberate. The removals land at the one version where a project is allowed to say "this changes." After that, a minor release should be safer to take than it was before.

The server changes that semver does not cover

The security work in the server is the part most likely to surprise a working deployment, because it changes defaults rather than adding features.

The release adds two explicit opt-ins: --allow-unauthenticated-tools and --media-allow-private-urls (pull requests #32113 and #32115). It also fixes handling of --cors-origins, blocks DNS rebinding and SSRF through the CORS proxy, prevents browser access to a child instance, and restricts HF_TOKEN to huggingface.co hosts.

Read those together and the shape is clear: behaviour that used to be available by default now requires a flag. That is the right direction for a server that increasingly exposes tools and fetches media on behalf of a model. It is also a behavioural change that the semantic version promise does not govern, since it lives in the server, not in ./include.

A concrete case: if your agents call a llama-server on a LAN address and rely on tool access, check the flag before you upgrade, and decide deliberately whether to opt in. The same goes for any workflow that feeds the model a media URL that resolves inside your network. The version number will not warn you about this. The release notes will.

What else landed in the same release

The feature list is not the story, but it explains why teams will want to take this release rather than sit on the last nightly:

| Area | Change in v1.0.0 | | --- | --- | | KV cache | FP8 caches via -ctk/-ctv f8_e4m3, with optional static per-tensor scales | | MoE inference | Host-memory expert cache with a configurable CPU share and LRFU/ClassLRU replacement | | Models | Kimi-K3.1-Pro, Ripple-65B-Preview, xing4_0, drama-3 TTS, MageVL-Cowork and Kimi-K3.1 vision | | Server | OpenAI-compatible /v1/audio/speech, request-state pinning with --sleep-idle-seconds, MCP tool cancellation on disconnect | | Tooling | Redesigned web UI with chat groups and a live markdown editor |

None of that changes the argument. A team shipping a local-model feature has more reasons than before to run a current build, and now a clearer rule for how far to trust the next one.

What a small team should do this week

The useful work is not upgrading. It is deciding what kind of dependency you have. A short pass:

Upgrade checklist

  1. Split your consumers into two lists: code that compiles against ./include, and processes that only speak HTTP to llama-server. They have different risks and different version numbers that matter.
  2. For compiled consumers, rebuild against the 1.0.0 headers and fix the removals. Start with llama_set_warmup, the defrag_thold field, llama_set_embd_state_src and any include of clip.h.
  3. For server deployments, read the security section before you roll. Set --allow-unauthenticated-tools and --media-allow-private-urls only where you actually intend them, then confirm your CORS origins still match the fixed parser.
  4. Set a pin policy per surface: allow patch and minor on the library if you compile against it, and treat a major bump as a scheduled migration with a test run.
  5. If you link ggml directly, or split inference across machines with its RPC backend, repeat step 2 and move every peer in the same window, since the protocol went to v9.

The output of that pass is a policy you can defend: which releases your build takes automatically, which one you read first, and which surface is still unreviewed.

The honest limit

A semantic version contract tells you when a break is allowed. It does not tell you that behaviour is unchanged, that performance is the same on your hardware, or that the server flags you pass still mean what they meant. The same release that promises stability also adds FP8 KV caches and six new model families, which is a lot of new code behind a promise that is one day old.

It is also a single-source claim. The promise comes from the project that has to keep it, and the first real test is a major bump that has not happened yet. What can be checked today is narrower and still useful: the rules are written down, the removals are listed, and the headers the promise covers are named.

That is more than most dependencies offer. It is also less than a guarantee, which is why the pin policy above still ends with your own test run rather than someone else's release notes.

If you are shipping a local-model feature and want a dependency policy that survives the next major release, get in touch.

Sources