Pin llama.cpp releases on your server
llama.cpp now cuts version tags beside its bNNNN build tags. Pin one, record it with the GGUF and quant, and treat every upgrade as a drill you can undo.
What changed in llama.cpp versioning
Pinning llama.cpp releases means building one named tag and recording that name beside the model file. The tag never moves on its own, so the server keeps producing tomorrow what it produced today. For years there was only one kind of tag to choose: a build number like b10502, cut from master automatically. Since 2026 there is a second kind, a version tag like v0.6.0, and the two tracks do not move in step. Build tags are created on almost every commit to master. Version tags are cut by a maintainer, by hand, at a slower pace, and each version release names the build tag that matches it.
The version tags started out tentative. The release notes on v0.1.2, published on 18 August 2026, said so in one line:
Semantic versioning is still work in progress. More info can be found in https://github.com/ggml-org/ggml/discussions/1579
Three days later v0.2.0 settled it. Its release notes say the release "marks the beginning of consistent semantic versioning for llama.cpp". They describe vX.Y.Z tags as stable versions with a slower release cadence, recommended for downstream distribution and casual users, and b[NUM] tags as nightly or dev builds with the latest functionality, recommended for developers and technical users. As of 14 November 2026 the latest version tag is v1.0.0, released on 13 November, and its notes name b12359 as the matching build tag.
The ggml discussion behind that link still holds the reasoning behind the scheme, and as of 21 October 2026 it is still open for feedback. Version numbering has reached 1.x, so read the notes before each move rather than judging an upgrade by which digit changed.
The number in a build tag carries no version meaning. It comes from the commit count, so it rises on its own whether or not anything relevant to your setup changed.
Never build from master on a box that serves anything
git pull followed by a rebuild gives you whatever landed in the last few hours. That is fine on a laptop. On a server it removes your ability to answer the question that matters when behaviour changes: what is running now, and what was running last week. The text a model produces and the speed it produces it at both move with the build. A complaint that answers got worse last Tuesday has no answer if Tuesday's commit was never written down.
Pin a tag instead. The project cuts them for you, and the prebuilt release archives carry a build tag in their filenames, apart from the Windows CUDA runtime bundles (cudart-llama-bin-win-...).
Which tag should you pin llama.cpp releases to?
Pin a build tag when you want one specific known state. This is the track with the long history, the track the release archives are named after, and the one most bug reports quote, so a build number is the easiest thing to compare with somebody else.
Pin a version tag if you would rather follow a shorter list of deliberate points. This is the track the project now recommends for downstream distribution. Each version release names its matching build tag, and the prebuilt binaries sit on that build tag, so record the build number next to the version. Read the notes before you move, even though the numbering has reached 1.x.
Either way the operational rule is identical. The tag string lives in a file, the box is rebuilt only when that string changes, and the change is a decision somebody made on purpose.
Build the pinned tag
sudo apt update
sudo apt install -y build-essential cmake git
git clone --depth 1 --branch b10502 https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp-b10502
cd ~/src/llama.cpp-b10502
git describe --tagsgit describe --tags should print b10502. A shallow clone at a tag holds that commit and nothing after it, so nobody can move it later with a careless git pull. If the configure step stops on a missing dependency, install what it names and run it again.
Build with the options your hardware needs. CPU only:
cmake -B build
cmake --build build --config Release -j $(nproc)NVIDIA GPU, which needs the CUDA toolkit installed first:
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)OpenBLAS on a CPU-only box:
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)Binaries land in build/bin, next to the shared libraries they load (libllama.so and the libggml files). Confirm the build runs before you install it:
./build/bin/llama-server --versionInstall the whole directory under a path named after the tag, then point one symlink at it:
sudo install -d /opt/llama.cpp/b10502
sudo cp -a build/bin /opt/llama.cpp/b10502/bin
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/currentCopy the directory, not the single file. A lone llama-server fails on its first run with error while loading shared libraries: libllama.so: cannot open shared object file, because the libraries it needs sit beside it in that directory.
Point the service at the symlink, never at a tag directory:
[Service]
ExecStart=/opt/llama.cpp/current/bin/llama-server -m /srv/models/model-q4_k_m.gguf -c 8192 -ngl 99 --host 127.0.0.1 --port 8080systemd resolves the symlink when it starts the process, so switching builds is a new symlink target plus sudo systemctl restart llama-server. The rest of the unit file and the reverse proxy in front of it are covered in the full walkthrough for a llama.cpp server on a VPS.
Record the tag beside the GGUF file and the quant
The build is half of what decides the output. The model file is the other half. GGUF (GGML universal file format) is the container the weights ship in, and the same model is published at many quantisation levels, so two servers on the same tag can still disagree because one holds a Q4_K_M file and the other a Q8_0. Keep one small file next to the model holding everything needed to rebuild the setup exactly:
tag: b10502
commit: 0adcc3b
model_file: model-q4_k_m.gguf
model_sha256: <output of sha256sum>
quant: Q4_K_M
cmake_args: -DGGML_CUDA=ON
cuda: <output of nvcc --version>
bench_cmd: llama-bench -p 512 -n 128 -r 5
bench_result: <fill in from the run on this box>Get the commit with git rev-parse --short HEAD inside the pinned checkout. Get the checksum with sha256sum model-q4_k_m.gguf, and compare it with the publisher's value at download time too, because checking a download against its published checksum catches a truncated file before it turns into a confusing bug. How much the quantisation level itself changes the answers is a separate question, and what each quantisation level costs you covers it.
How do you upgrade without breaking the server?
Run the upgrade as a drill. Build the new tag beside the old one, measure both, and keep the old one until the new one has won.
- Clone the new tag into its own directory. Do not reuse the old checkout.
- Build it with the same cmake arguments recorded in the manifest.
- Run
llama-benchon both builds against the same model file, with the same prompt length and the same repetition count. - Send a prompt whose answer you know well through both servers and read the two replies.
- Move the symlink, restart the service, and leave the old directory on disk.
/opt/llama.cpp/b10502/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5
/opt/llama.cpp/<new tag>/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5llama-bench prints one row per test, with a backend column, an ngl column and a tokens per second column carrying its standard deviation. Compare the same row between the two builds, not one build's prompt row against the other's generation row. A figure taken at a different prompt length is a different measurement, which is why measuring tokens per second the same way every time matters more than the number itself.
Rolling back is two commands, and it works only because the old directory is still there:
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-serverKeep at least the previous build. It costs a fraction of the disk the model file beside it already uses.
What breaks across llama.cpp upgrades
A model file stops loading. This is usually what makes people upgrade in the first place: a newly published model uses an architecture the pinned build does not know, so it never loads. llama-server exits during startup. As of 21 October 2026 the server source logs failed to load model, '/srv/models/model-q4_k_m.gguf' for this, with a comma and the path in single quotes, and the last line it prints is exiting due to model loading error, which carries no path. Grep the journal for failed to load model rather than for the full line. Read the lines printed just before it, including the loader's own error loading model: line, which show how far the loader got and why it stopped. GGUF also carries a format version in its header (the spec's current value is 3, and version 2 widened the length fields from 32 to 64 bits), though in practice an unknown architecture name stops you long before the format version does. The fix is a newer tag, chosen and written down.
A server flag is renamed or deprecated. An unrecognised flag stops llama-server at startup rather than being ignored, which under systemd looks like a service that starts and dies in a loop. journalctl -u llama-server -n 50 shows the real message. As of 19 August 2026 the server documentation marked --mlock and --mmap as deprecated in favour of -lm, --load-mode. As of 21 October 2026 neither flag appears in the server documentation or in the argument list on master any more, so carry the behaviour over with --load-mode, which takes auto (the default), none, mmap, mlock, mmap+mlock and dio. The GPU offload flag is documented as -ngl, --gpu-layers, --n-gpu-layers, so the long spelling in older guides is still accepted. Defaults move too: since v0.7.0 llama-server listens on port 9931 by default instead of 8080 (the Docker images keep 8080 inside the container), so a unit file that leaves out --port stops answering where your reverse proxy expects it. The v1.0.0 release also removes the deprecated --defrag-thold flag. Before you move the symlink, run /opt/llama.cpp/<new tag>/bin/llama-server --help and check every flag in your unit file against it.
A build option is renamed. The CMake options moved from a LLAMA_ prefix to a GGML_ prefix, and the root CMakeLists.txt still carries the mapping. LLAMA_CUBLAS is now a fatal error naming GGML_CUDA as its replacement, while LLAMA_CUDA and LLAMA_METAL produce a warning and are translated for you. A build script that stops at the configure step is the good outcome. The quiet failure is worse: leave out -DGGML_CUDA=ON by accident and the build succeeds, the server starts, and everything runs on the CPU. llama-bench shows it at once, because the backend column reads CPU.
The accelerator build is not portable. As of 19 August 2026 the Linux assets attached to a build tag were the CPU, Vulkan, SYCL and OpenVINO variants, for x64, arm64 and s390x, with no CUDA archive for Linux. That has since changed. As of 21 October 2026 b11669, the build tag behind v0.7.0, also carries Ubuntu CUDA archives for CUDA 12.8 and 13.4 on x64 and CUDA 13.4 on arm64, each with a matching cudart- runtime archive, plus a ROCm build. The CUDA archives are published per toolkit version on Linux and Windows alike, which is a useful hint: the toolkit version is part of what identifies your binary, so record it alongside the cmake arguments.
Pinning the container image instead
Same rule, different noun. The published images (ghcr.io/ggml-org/llama.cpp:server and its accelerator variants) are moving names, so pulling :server next month gives you a different program under the same label. Pull once and read the digest:
docker pull ghcr.io/ggml-org/llama.cpp:serverdocker pull prints a Digest: sha256:... line. Put that digest in the compose file in place of the tag, and the image cannot change under you the next time somebody runs docker compose pull. Keep the previous digest in a comment so a rollback is one edit, the same way the upgrade and rollback routine for a Compose stack treats every other service.
The point of a pin
A pin lets you say exactly what is running, and it lets you put the previous build back within a minute when a change makes things worse. llama.cpp asks you to track two things for that, the build tag and the model file, because it hands you the two separately. Runtimes that bundle them behave differently, and the comparison of Ollama and llama.cpp as servers covers that trade: one version number over the whole thing is less to record and less to control.
FAQ
Should I pin the bNNNN build tag or the v0.x tag?
Either works, as long as you pin something. Build tags such as b10502 are the long-running track: the prebuilt release archives carry one in their filenames (the Windows CUDA runtime bundles aside) and most bug reports quote one, so a build number is the easiest thing to compare with another operator. Version tags such as v0.6.0 are a shorter list of deliberate points that the project recommends for downstream distribution, which suits a server you touch a few times a year. Each one names its matching build tag, so record both. What matters more than the choice is that the tag string sits recorded next to the model file, and that upgrading is a decision rather than a side effect of git pull.
Does llama.cpp follow semantic versioning now?
Yes, since v0.2.0 on 21 August 2026. Its release notes say it marks the beginning of consistent semantic versioning for llama.cpp, replacing the work-in-progress caveat that v0.1.2 carried. As of 14 November 2026 version numbering has reached 1.x, the latest being v1.0.0, released on 13 November. Read the release notes before moving, and test the new tag against your own model file before switching to it, whichever digit changed.
How do I tell which llama.cpp build my server is running?
llama-server --version prints the version and build information, so run it against the binary the service uses: /opt/llama.cpp/current/bin/llama-server --version. As of 21 October 2026 the startup line that carries the build number, commit hash and compiler is logged at trace level, so do not count on finding it in journalctl -u llama-server at the default log level. On a source install, git describe --tags inside the pinned checkout prints the tag, and readlink /opt/llama.cpp/current shows which directory the service is actually pointed at.
Why did my model stop loading after I upgraded llama.cpp?
A load failure straight after an upgrade is a mismatch between the build and the GGUF file. The log carries a failed to load model, '<path>' line naming the file and ends with exiting due to model loading error, and the lines above them show how far the loader read. Moving forwards, a very new model file needs a build that knows its architecture. Moving backwards, a rollback below the tag the file was made for can break a file that worked yesterday. Point the symlink at the previous build, restart, and confirm which build and file paired correctly before deciding which of the two to change.
Are there prebuilt Linux binaries I can pin instead of building?
Yes. Each build tag carries release archives named after it, such as llama-b10502-bin-ubuntu-x64.tar.gz, so the tag is in the filename and pinning is easy. On 19 August 2026 the Linux set was CPU, arm64, s390x, Vulkan, SYCL and OpenVINO, with no CUDA archive. As of 21 October 2026 the newer b11669 also carries Ubuntu CUDA 12.8 and 13.4 archives with matching cudart- runtime bundles, so an NVIDIA server on a recent tag no longer has to build from source with -DGGML_CUDA=ON or run a CUDA container image. If you pin a version tag, download the archives from the build tag its release notes name.