llama.cpp v1.0.0, released on November 13, 2026, is the first version where the project promises semantic versioning for its C library: from now on a breaking change to the public API in ./include means a major-version bump. To get there, the release deletes the old deprecated functions, a KV-cache option and the clip.h header, and tightens several llama-server security defaults. This guide lists what can break when you upgrade from v0.9.x, how to fix each case, and what is worth trying once you are on 1.0.
Who actually needs to worry
Not everyone who runs llama.cpp hits a breaking change. Before you read the whole list, place yourself in one of three groups:
- You only run the prebuilt binaries (
llama-cli,llama-server) with a model and a few flags. Most of your setup keeps working. Check two things: whether your scripts pass-dt/--defrag-thold, and whether your server uses tools, MCP, a CORS proxy or media URLs on a local network. - You link against
libllamafrom C, C++ or a language binding. This is the group the release is about. If your code still calls functions that were markedDEPRECATEDinllama.h, it will no longer compile, because those declarations are gone. - You build on the multimodal code and include
clip.hdirectly. That header was removed and its code was consolidated intomtmd.
If you use llama.cpp only through another app, the upgrade is that app's job: wait for its maintainers to ship a build against v1.0.0 rather than swapping the library underneath it.
What the 1.0 version number promises
The Hugging Face blog post that accompanied the release explains the versioning rules that now apply to ggml-org projects. A MAJOR bump means a breaking change to the public C API in ./include; a MINOR bump covers backward-compatible features, backend updates, model support or API additions; a PATCH bump is a bug fix with no API change. Two libraries are covered: libllama (public headers in llama.cpp/include/) and libggml (headers in ggml/include/), and ggml was bumped to v1.0.0 at the same time.
In practice this gives you something you did not have before: you can pin 1.x in a package manager or CMake script and expect your code to keep compiling across minor releases. Nightly build tags such as b12359 still exist next to the semantic versions, so decide which one your build pins and write it down.
Breaking change 1: deprecated llama.h functions are gone
Pull request #30565 ("llama : prune") removed all 35 functions that were marked DEPRECATED in llama.h, plus llama_set_warmup. The good news is that every removed declaration carried a message naming its replacement, so the migration is mostly search-and-replace. The ones you are most likely to have in older code:
llama_load_model_from_file→llama_model_load_from_filellama_free_model→llama_model_freellama_new_context_with_model→llama_init_from_modelllama_n_ctx_train,llama_n_embd,llama_n_layer,llama_n_head→ thellama_model_n_*versionsllama_n_vocab→llama_vocab_n_tokensllama_token_bos,_eos,_eot,_nl,_padand thellama_token_fim_*family → the matchingllama_vocab_*functionsllama_token_get_text/_score/_attrandllama_token_is_eog/_is_control→llama_vocab_get_*andllama_vocab_is_*llama_add_bos_token/llama_add_eos_token→llama_vocab_get_add_bos/llama_vocab_get_add_eosllama_get_state_size,llama_copy_state_data,llama_set_state_data→llama_state_get_size,llama_state_get_data,llama_state_set_datallama_load_session_file/llama_save_session_file→llama_state_load_file/llama_state_save_filellama_sampler_init_grammar_lazy→llama_sampler_init_grammar_lazy_patterns
Note that the token helpers now take a llama_vocab pointer, not the model. If your old code passed the model around, get the vocab once after loading and pass that.
How to fix it step by step
- Before upgrading, build your project against v0.9.x with deprecation warnings visible (do not silence
-Wdeprecated-declarations). Every warning is a line that will fail on 1.0. - Replace each call with the name from the deprecation message (the list above, or our table at the end of this post).
- Rebuild against v0.9.x until the warnings are gone. Your code is now compatible with both versions, which makes the switch safe to roll back.
- Bump to v1.0.0 and rebuild. Anything left is either
llama_set_warmup,defrag_tholdor the renamed state function covered below.
llama_set_warmup and the renamed state call
llama_set_warmup has no direct replacement; its deprecation note said user code should do warmup runs manually. If you relied on it, run a short throwaway decode yourself before serving real requests. Separately, the speculative-decoding ("NextN") functions that lived in llama-ext.h were promoted to llama.h, and llama_set_embd_state_src was renamed to llama_set_ctx_state_src. That one is a pure rename.
Breaking change 2: --defrag-thold and defrag_thold
The same pull request removed the deprecated defrag_thold field from llama_context_params and the -dt / --defrag-thold command-line option. If a systemd unit, Docker command or launcher script still passes the flag, remove it; the option no longer exists in v1.0.0's argument list. In C/C++ code, delete the line that sets params.defrag_thold.
Breaking change 3: clip.h was removed
Pull request #31865 removed clip.h and moved the vision/audio model infrastructure into mtmd, with mtmd_context as the public handle. The PR author describes clip.h as an internal header that no longer made sense on its own. If your code included it, move to the public mtmd.h / mtmd-helper.h APIs; there is no compatibility shim. The release also makes some vision projectors stricter at load time (required projector and patch-embedding tensors, a 2x2 spatial merge for Qwen-VL projectors), so a malformed or very old mmproj file that used to load may now be rejected. Re-download or re-convert it.
Breaking change 4: llama-server security defaults
This is the change most likely to surprise people who never touch C code. Several server behaviours that used to be allowed now need an explicit opt-in:
- Tools or MCP on a network address without an API key are refused. If you start the server with
--hostset to a non-loopback address and enable tools, MCP servers or the MCP proxy without an API key, it is now refused with an error. Fix: set--api-key(or--api-key-file). The escape hatch--allow-unauthenticated-toolsexists, and the docs describe it as "only for trusted networks". - Media URLs to private addresses are blocked. An
image_urlpointing at a NAS or another machine on your LAN is now refused by default. Fix: add--media-allow-private-urlsif you trust that network, or send the image as base64 instead. - The CORS proxy only reaches public addresses. According to PR #32115, using the web UI's CORS proxy to reach an MCP server on
localhostor your LAN is no longer possible, and there is no flag to bring it back. Point the client directly at the MCP server instead. --cors-originsnow checks the port. An origin written ashttp://domain:PORTmust match exactly, so a frontend on a different port than the one you listed will start failing CORS checks. List every origin you actually use.HF_TOKENis only sent to huggingface.co hosts, so a custom mirror that relied on receiving it will now see anonymous requests.
Comparison: where llama.cpp 1.0 sits next to Ollama and vLLM
All three are free, open-source local inference engines; what differs is the interface and how they version. Facts below come from each project's GitHub repository and latest release, checked today.
| Project | License / price | Latest release (as of Nov 15, 2026) | Main interface | Versioning note |
|---|---|---|---|---|
| llama.cpp | MIT, free | v1.0.0 (Nov 13, 2026) | C/C++ library (libllama), CLI, llama-server with OpenAI-compatible endpoints |
Semantic versioning for the public C API starts with 1.0 |
| Ollama | MIT, free | v0.40.16 (Nov 9, 2026) | Go app with its own CLI and local API | Still on 0.x releases |
| vLLM | Apache-2.0, free | v0.33.0rc3 (Nov 2, 2026) | Python serving engine for GPU servers | Still on 0.x releases |
If you embed inference in your own program, llama.cpp is now the only one of the three with a written API-stability promise. If you just want a local chat model with minimal setup, the upgrade notes above matter less than whichever tool you already know.
Worth trying after you upgrade
/v1/audio/speech. An OpenAI-compatible text-to-speech endpoint for models that can generate audio. Read the details before you drop in an OpenAI client: the default format iswav(notmp3), onlywavandpcmare accepted, OpenAI voice names likealloyare not mapped,speedmust be1.0, and the sample rate is the model's own rather than 24 kHz.- FP8 KV cache.
-ctk f8_e4m3 -ctv f8_e4m3stores the KV cache in FP8, with optional static per-tensor scales. - MoE expert cache. New
moe_cache_sizeandmoe_cache_cpu_sharecontext parameters keep MoE experts in host memory with a configurable CPU share. - Redesigned web UI. Chat groups in the sidebar, a live-preview markdown editor, PDF thumbnails and a mobile layout.
Editor's note
Upgrade now if: you maintain code against libllama and want the stable-API guarantee, or you expose llama-server on a network and want the tighter defaults.
Wait if: you use llama.cpp only through another app, or you depend on reaching LAN MCP servers through the web UI's CORS proxy, which has no opt-in.
Common errors and fixes: "undeclared identifier llama_load_model_from_file" (or any old llama_token_* name) means a removed deprecated call: use the replacement above. An unknown-argument error for -dt means delete the flag. The server refusing to start with tools on 0.0.0.0 means you need --api-key. Images from a LAN URL failing means --media-allow-private-urls or base64.
What we checked: everything here comes from the v1.0.0 release notes, the linked pull requests, the deprecation messages in the removed llama.h lines and the v1.0.0 server README. We did not benchmark the new features, so this post makes no speed claims.
FAQ
Do I have to rewrite my app to use llama.cpp 1.0?
No. If you already moved off the deprecated functions, most code compiles unchanged. If not, the work is mostly renaming calls, because each removed function had a named replacement.
Will my GGUF models still work?
The release does not announce a GGUF format break. The exception is multimodal projector (mmproj) files, which now get stricter checks at load time; if one is rejected, get a fresh copy of it.
Can I stay on v0.9.0?
Yes, older releases remain on GitHub. But the security fixes for llama-server (CORS, DNS rebinding, SSRF) are in the 1.0 line, so do not leave an old server exposed on a network.
Related reading on lightmind24
- Ollama Not Working? Fixes for Pull, GPU and API
- vLLM Errors Fixed: Out of Memory, CUDA and Chat Templates
- LiteLLM Tutorial: One Proxy for OpenAI and Ollama
Bottom line: fix the deprecation warnings on v0.9.x first, then upgrade, and check your server flags if it listens on anything other than localhost.
Screenshots of the llama.cpp v1.0.0 release notes and the versioning rules, plus our own migration table, are included at the end of this post. Image credit: screenshots from github.com/ggml-org/llama.cpp and huggingface.co/blog; migration table by lightmind24.
lightmind24 is an independent review site, not affiliated with ggml-org, Hugging Face, Ollama or vLLM.
Last verified: 2026-11-15
Sources:
llama.cpp v1.0.0 release notes
llama.cpp v1.0.0: A stronger foundation for the local AI ecosystem (Hugging Face blog)
PR #30565: llama : prune
PR #31865: remove clip.h, consolidate into mtmd
PR #32113: explicit opt-in tools via non-loopback address
PR #32115: disallow local addresses from CORS proxy and media URLs
llama-server README (v1.0.0)
Ollama on GitHub
vLLM on GitHub
댓글
댓글 쓰기