· 6 min read

llama.cpp Hit 1.0 After 3.5 Years and Now Uses Semantic Versioning. The Guarantee Covers the C API, Not Everything You Probably Depend On.

On November 13, the ggml-org team published "llama.cpp v1.0.0: A stronger foundation for the local AI ecosystem," and tagged ggml v1.0.0 the same morning. After 3.5 years of build-number releases, both libraries now follow semantic versioning: a major bump means a breaking change to the public C API. That's good news if you link against libllama. If you run llama.cpp as a CLI or a server behind your app, which is how most solo builders I know use it, the promise is narrower than the headline suggests.

What the new rules say

The release post lays out the rules in a short table. MAJOR is a "breaking change to the public C API in ./include." MINOR covers backward-compatible features, backend updates, new model support and API additions. PATCH is a bug fix with no API change. The scope is the two libraries, libllama with its header in llama.cpp/include/ and libggml with its header in ggml/include/.

In the prose, the team says both projects will reflect API and ABI incompatibilities with major-version bumps, and that they "will be stricter about making those boundaries visible to downstream consumers." There's a small gap between the table, which says C API, and the prose, which adds ABI. I'd read that as intent to cover both, but there is no written deprecation window yet.

The post also says llama.cpp now supports more than 150 architecture variants, and lists the distribution channels: Docker, Debian, Homebrew, conda-forge, MacPorts and Winget among them.

What ggml 1.0 changed

The ggml v1.0.0 release notes run since v0.29.0 and include an "API changes" section. Two items stand out. The team "pruned deprecated API" and removed the legacy DIAG_MASK_INF and DIAG_MASK_ZERO ops. And the RPC protocol was bumped to version 9 so that servers reject incompatible peers.

The first one matters if you maintain bindings or a fork that still calls old functions. The second one matters if you split inference across machines with ggml's RPC backend. Mixed versions that used to limp along will now refuse to connect, which is the right behavior and also a surprise if you upgrade one box and not the other.

What the announcement doesn't cover

This is the part I'd want to know before upgrading anything in production. The release post doesn't say whether these layers are covered by the semver promise:

  1. CLI flags for llama-cli and friends
  2. The llama-server HTTP API, including its OpenAI-compatible endpoints
  3. The GGUF file format

It also doesn't say what happens to the old bNNNN build tags, and the post gives no guidance for downstream projects like Ollama or LM Studio. The team links a GitHub discussion on releases and versioning, and that's where I'd expect those answers to show up.

I'm not saying those layers will break. GGUF has been stable in practice for a long time, and the server has kept its endpoints fairly steady. I'm saying "1.0" is a promise about the C headers, and if your product talks to llama-server over HTTP, you are relying on habit rather than a written guarantee.

How I'd pin a local AI stack now

If you link libllama or libggml directly, pin to the 1.x range and let minor and patch updates through. That's the whole point of the new scheme, and it should cut down the "rebuild, find a renamed function, patch" cycle that bindings maintainers know too well.

If you use the server, I'd still pin an exact version and upgrade on purpose. Keep a small contract test: one request each to the chat completion, embeddings and health endpoints your app uses, with assertions on the response shape, not the text. Run it on every upgrade. It takes ten minutes to write and it catches the change the semver table doesn't promise to flag.

If you run RPC across machines, upgrade all nodes together. With protocol v9, a mismatched node won't join, so plan the rollout like a database migration rather than a rolling restart.

And if you ship GGUF files to users, keep the llama.cpp version you converted them with written down next to each file. If the format ever does change, that note is what lets you reconvert quickly.

Where I could be wrong

It's possible the maintainers consider the server API and GGUF covered by spirit even if the table doesn't list them, and the discussion thread may already say so. If that's the case, my extra pinning is belt and braces. It's also possible that most solo builders never touch llama.cpp directly and only see it through Ollama or LM Studio, in which case the right move is to watch what those projects do with 1.x, not to change anything yourself.

I'd still rather write the contract test than assume. The cost of being wrong in that direction is ten minutes.

What I'd actually do

This week: bump to 1.0 on a dev machine, run your one-page contract test against llama-server, and note the exact version in your README or deploy config. If you use RPC, upgrade every node in one go. Then read the linked versioning discussion and see whether CLI, server and GGUF get named. Until they do, treat 1.0 as a stable library and a still-moving tool.

Author

Sources

Newsletter

The week, in one email.

The weekly summary of what happened and what it means for people who build alone. No spam, unsubscribe any time.

Form not showing? Subscribe on this page instead.

Related Posts