vcpkg computes an ABI hash for every build and reuses a cached binary only when the hash is identical. The hash covers the port files, triplet, compilers, selected features, CMake version and the hash of each dependency, so a patched port or a changed compiler forces a rebuild.
What the hash includes
Microsoft's binary caching reference lists the inputs. Among them:
- Every file in the port directory
- The triplet file contents and name
- The C and C++ compiler executables
- The set of features selected
- The ABI hash of each dependency
- Helper functions referenced by the portfile (heuristic)
- The version of CMake, and of PowerShell on Windows
- The toolchain file's text, and the values of passthrough environment variables
The documentation adds that this is an implementation note that will change without notice, and that despite the long list it is possible to defeat the cache and introduce nondeterminism.
What that means for a library fix
When a new library release arrives, the port in the registry changes: the portfile points to the new source and its checksum. That changes the port files, so the hash changes and vcpkg rebuilds. A baseline update that pulls in the new port therefore produces a fresh build.
Because the hash includes the ABI hash of each dependency, a fix to a low level library such as a compression library cascades: everything that depends on it also gets a new hash and rebuilds. That is useful for security, since nothing keeps linking an old copy through a stale cache.
What can go wrong
| Situation | Result |
|---|---|
| Port files, compiler and dependencies unchanged | Hash is the same, so the cached binary is reused as intended |
| Different CI runners with different compilers | Different hashes, so rebuilds or cache misses |
| Shared cache across teams | One team's binary is trusted by another |
Two points follow. First, a shared binary cache is a trust decision: whoever can write to it can influence what others link. Control write access and use read-only mode for most users. Second, record the ABI hash alongside each release. The hash is stored in each package and in the installed directory under share, port name, in a file called vcpkg_abi_info.txt, so you can inspect it.
Steps to check a fix reached your build
- Update the baseline or add a version constraint for the fixed release.
- Run the build with debug output if you need to see why a package was rebuilt.
- Compare the vcpkg_abi_info.txt of the old and new builds.
- Confirm the package version in the generated SBOM matches the fixed release.
- Keep the evidence with the release record.
See how to get an SBOM from a vcpkg project for where the version is recorded.
Quick check
Does a baseline update always rebuild?
If it changes the port files or any dependency hash, yes. The hash decides.
Can I rely on the hash format staying the same?
The documentation calls it an implementation note that will change without notice. Do not parse it in tooling.
Safeguard's SBOM and dependency scanning can build an inventory of the components in a repository, and the free scan at gold.safeguard.sh/scan is a quick way to see what turns up.
Sources
Last reviewed: 19 October 2026.
