vcpkg: Troubleshooting & Dependency Lifecycle

Reference for the vcpkg skill. Use this when a user encounters vcpkg build failures, package-not-found errors, needs to read build logs, or manages the dependency lifecycle (removing, changing features, replacing libraries, cleaning the cache).

Reading vcpkg Build Logs

Build logs are stored at:

<vcpkg-root>/buildtrees/<port-name>/

Key log files:

config-<triplet>-out.log — CMake configure output
build-<triplet>-<dbg|rel>-<out|err>.log — common build logs
install-<triplet>-<dbg|rel>-<out|err>.log — common install logs

Exact names vary by port and build helper; use the path vcpkg prints for the failing command.

When a build fails, vcpkg prints the path to the relevant log. Start with the -err.log file for the failing step.

Resolving package-not-found After Install

If CMake says Could not find a package configuration file provided by "X":

Check toolchain file — ensure -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake is set
Check triplet match — the installed triplet must match your build architecture
Check package name — vcpkg port names may differ from CMake package names (e.g., port nlohmann-json → find_package(nlohmann_json))
Check installed list — run vcpkg list to confirm the package is actually installed
Clear CMake cache — delete CMakeCache.txt and reconfigure

Dependency Lifecycle

Removing a Library

Remove it from vcpkg.json → "dependencies" array
Run vcpkg install to reconcile (manifest mode auto-removes unused packages)

In classic mode:

vcpkg remove boost-regex
vcpkg remove boost-regex --recurse  # also removes dependents

Changing Features on an Installed Library

Update the features in vcpkg.json:

{
  "dependencies": [
    {
      "name": "curl",
      "features": ["ssl", "ssh"]
    }
  ]
}

Then run vcpkg install — vcpkg will detect the feature change and rebuild.

In classic mode:

vcpkg install curl[ssl,ssh] --recurse   # permits rebuilding with the new feature set

Replacing One Library with Another

Remove the old library from vcpkg.json
Add the new library to vcpkg.json
Run vcpkg install to reconcile
Update your source code: change #include directives, find_package() calls, and target_link_libraries() in CMakeLists.txt

Cleaning the vcpkg Cache

# Remove build trees
Remove-Item -Recurse -Force <vcpkg-root>\buildtrees

# Remove downloaded archives
Remove-Item -Recurse -Force <vcpkg-root>\downloads

# Remove installed packages (classic mode only)
Remove-Item -Recurse -Force <vcpkg-root>\installed

# Remove package build artifacts
Remove-Item -Recurse -Force <vcpkg-root>\packages

# In manifest mode, remove the local vcpkg_installed directory
Remove-Item -Recurse -Force .\vcpkg_installed

rm -rf <vcpkg-root>/buildtrees
rm -rf <vcpkg-root>/downloads
rm -rf <vcpkg-root>/installed
rm -rf <vcpkg-root>/packages
rm -rf ./vcpkg_installed

3.0 KiB Raw Blame History