Libraries do not share one version format, and vcpkg deliberately will not compare versions that use different schemes. Matching a library to a vulnerability advisory has the same problem, so record the exact upstream version string plus how it was derived instead of relying on a guess.
The four schemes
The vcpkg versioning reference lists these manifest properties.
| Property | Meant for |
|---|---|
| version | Dot separated numeric versions |
| version-semver | Semantic versioning compliant versions |
| version-date | Dates in the format YYYY-MM-DD |
| version-string | Arbitrary strings |
A manifest may contain only one. The reference says that by design vcpkg does not compare versions that use different schemes, giving the example that a version-string of 7.1.3 cannot be compared with a version of 7.1.4 even if the conversion seems obvious.
There is also a port version, tracking changes to packaging files without a change in the upstream library version. It is written after a hash sign, so 1.2.0#2 means version 1.2.0, port version 2.
Why it matters for security
An advisory says affected versions up to some release. To decide whether you are affected, a tool or a person must order your version against that range. That is easy for numeric versions and hard for dates or free strings.
Three risks follow:
- Wrong ordering. A date style version can be read as a number and ordered incorrectly.
- Packaging changes hidden. A port version bump may carry a patch that changes exposure, yet the upstream version stays the same.
- Fork or snapshot versions. A library at head of a repository may have no release number that an advisory can name.
What to record in your inventory
- The upstream project name and the exact version or commit.
- The scheme or source it came from.
- Any port or patch level that your packaging added.
- A note when the version is a snapshot with no release.
Resolving unclear cases
When a scanner cannot decide, do not assume you are safe. Check the project's own advisory text and the commit history to see whether the fix is in your snapshot. Record the answer so the next person does not repeat the work.
A habit
When you add a dependency, state its version in the form the upstream project uses, and note it in your SBOM beside the build system's own label.
Where Safeguard fits
If you want an inventory your reviewers can query, Safeguard offers SBOM and dependency scanning with policies and gates on pull requests. It works from the source and manifests it supports. A free scan is at gold.safeguard.sh/scan.
Quick check
Does a port version mean a newer library?
No. It tracks changes to packaging files without a change to the upstream version.
Can a date based version be compared with a numeric one?
In vcpkg, no. It will not compare across schemes, so do not mix them for one package.
Sources
Last reviewed: 19 October 2026.
