An overlay port is a port definition vcpkg loads from a folder on disk instead of from the registry. Overlay ports take priority when vcpkg resolves a name, so a copy of a port with your patch added will be used in place of the registry version. Track it, because it will not update itself.
How overlays work
Microsoft's documentation says an overlay port can act as a drop-in replacement for an existing port or as a new port not available in a registry, and that overlay ports take priority while names are resolved.
You can add overlay directories three ways, evaluated in this order:
- The command line, with the overlay ports option.
- The overlay-ports array in vcpkg-configuration.json.
- The VCPKG_OVERLAY_PORTS environment variable.
When resolving a name, the first location containing a matching overlay port is used. A valid port has a portfile.cmake and either a vcpkg.json or a CONTROL file.
Steps to ship a patched library
- Copy the existing port directory from the registry into a folder in your repository, for example overlay-ports followed by the library name.
- Add your patch file next to the portfile and apply it from the portfile after the source is extracted.
- Increase the port version in vcpkg.json so a changed port can be told apart from the original. The versioning reference defines port versions as a non-negative number that rises with each change to packaging without a new upstream version.
- Reference the folder in vcpkg-configuration.json so every developer and CI run uses it.
- Commit the folder, with a note saying why the patch exists and when to remove it.
Why a patched port rebuilds
vcpkg computes an ABI hash for each build and treats equal hashes as identical. The hash covers every file in the port directory, so adding a patch changes it and prevents a stale cached binary from being reused. See what triggers a rebuild in vcpkg binary caching.
The risk: a forgotten overlay
Overlay precedence is the point, and also the hazard. If upstream later releases a fixed version, your overlay still wins, so you can sit on an old library long after the registry has a better one.
Protect against that:
- Put an expiry in the overlay README, tied to the upstream fix or release.
- Add a CI check that lists overlay ports and fails when one is older than your limit.
- List overlay ports in the SBOM with their patched status.
- Prefer sending the patch upstream so the overlay can go away.
Try it yourself
Open the demo and check how a fix that is available now is shown against a component. Think about how you would notice that an overlay had become unnecessary.
Click through it at your own pace, or open it full screen.
Quick check
Does an overlay port beat the registry?
Yes. Overlay ports take priority when vcpkg resolves a package name.
Will an overlay pick up upstream fixes?
No. It stays as you wrote it until you update it, so add an expiry and a CI check.
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
- Overlay ports, Microsoft Learn
- Versioning reference, Microsoft Learn
- Binary caching configuration, Microsoft Learn
Last reviewed: 19 October 2026.
