vcpkg Cheat Sheet

Overview

vcpkg is a free, open-source C/C++ package manager maintained by Microsoft. It provides access to thousands of open-source libraries and integrates seamlessly with CMake and MSBuild. vcpkg supports classic mode (system-wide installs) and manifest mode (per-project dependency declarations in vcpkg.json).

vcpkg handles building libraries from source with consistent configurations across Windows, Linux, and macOS. It supports custom triplets for targeting different architectures, compilers, and linkage types, making it suitable for cross-platform C++ development.

Installation

Clone and Bootstrap

# Clone the repository
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg

# Bootstrap on Linux/macOS
./bootstrap-vcpkg.sh

# Bootstrap on Windows
.\bootstrap-vcpkg.bat

# Add to PATH
export VCPKG_ROOT="$HOME/vcpkg"
export PATH="$VCPKG_ROOT:$PATH"

Set Environment Variables

# Add to ~/.bashrc or ~/.zshrc
export VCPKG_ROOT="$HOME/vcpkg"
export PATH="$VCPKG_ROOT:$PATH"

# For CMake integration
export CMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"

Core Commands

Command	Description
`vcpkg install <pkg>`	Install a library
`vcpkg remove <pkg>`	Remove a library
`vcpkg search <term>`	Search available packages
`vcpkg list`	List installed packages
`vcpkg update`	Check for outdated packages
`vcpkg upgrade`	Rebuild outdated packages
`vcpkg integrate install`	Enable system-wide MSBuild integration
`vcpkg export`	Export installed packages
`vcpkg edit <pkg>`	Edit a port’s portfile
`vcpkg new`	Create a new manifest (vcpkg.json)

Installing Packages

# Install a package (default triplet)
vcpkg install zlib

# Install specific triplet
vcpkg install zlib:x64-linux
vcpkg install zlib:x64-windows-static
vcpkg install zlib:arm64-osx

# Install multiple packages
vcpkg install boost fmt spdlog nlohmann-json

# Install with features
vcpkg install curl[openssl,http2]
vcpkg install opencv4[contrib,ffmpeg,qt]

Manifest Mode (Recommended)

Create vcpkg.json

# Initialize manifest in current project
vcpkg new --application

{
  "name": "my-project",
  "version-semver": "1.0.0",
  "dependencies": [
    "fmt",
    "spdlog",
    {
      "name": "boost",
      "version>=": "1.83.0"
    },
    {
      "name": "curl",
      "features": ["openssl", "http2"]
    }
  ],
  "builtin-baseline": "a1a1cbc975402e753c76afb386b4390db5326e9f"
}

CMake Integration

# CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(myproject)

find_package(fmt CONFIG REQUIRED)
find_package(spdlog CONFIG REQUIRED)

add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE fmt::fmt spdlog::spdlog)

# Configure with vcpkg toolchain
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

# Or set via preset (CMakePresets.json)
cmake --preset default

CMake Presets

{
  "version": 3,
  "configurePresets": [
    {
      "name": "default",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

Configuration

Triplets

# List available triplets
ls $VCPKG_ROOT/triplets/

# Common triplets
# x64-linux          - 64-bit Linux, dynamic
# x64-windows        - 64-bit Windows, dynamic
# x64-windows-static - 64-bit Windows, static
# x64-osx            - 64-bit macOS, dynamic
# arm64-osx          - Apple Silicon macOS

# Set default triplet
export VCPKG_DEFAULT_TRIPLET=x64-linux

Custom Triplet

# custom-triplets/x64-linux-static.cmake
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)
set(VCPKG_CMAKE_SYSTEM_NAME Linux)
set(VCPKG_BUILD_TYPE release)

# Use custom triplet
vcpkg install zlib --overlay-triplets=custom-triplets --triplet=x64-linux-static

Version Constraints (vcpkg.json)

{
  "name": "my-project",
  "version-semver": "1.0.0",
  "dependencies": [
    { "name": "fmt", "version>=": "10.0.0" }
  ],
  "overrides": [
    { "name": "zlib", "version": "1.2.13" }
  ],
  "builtin-baseline": "a1a1cbc975402e753c76afb386b4390db5326e9f"
}

Advanced Usage

Binary Caching

# Enable filesystem cache (default)
export VCPKG_BINARY_SOURCES="clear;files,$HOME/.cache/vcpkg/archives,readwrite"

# Use NuGet feed
export VCPKG_BINARY_SOURCES="clear;nuget,https://myfeed.example.com/nuget/v3/index.json,readwrite"

# Use GitHub Packages
export VCPKG_BINARY_SOURCES="clear;x-gha,readwrite"

# AWS S3 caching
export VCPKG_BINARY_SOURCES="clear;x-aws,s3://my-bucket/vcpkg-cache/,readwrite"

Creating Custom Ports

# Create overlay port structure
mkdir -p overlay-ports/mylib

# overlay-ports/mylib/portfile.cmake
vcpkg_from_github(
  OUT_SOURCE_PATH SOURCE_PATH
  REPO myorg/mylib
  REF v1.0.0
  SHA512 abc123...
)

vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")
vcpkg_cmake_install()
vcpkg_cmake_config_fixup()
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")

# Install from overlay
vcpkg install mylib --overlay-ports=overlay-ports

Exporting Packages

# Export as raw files
vcpkg export zlib fmt --raw --output=exported-libs

# Export as zip
vcpkg export zlib fmt --zip --output-dir=./exports

# Export as NuGet package
vcpkg export zlib fmt --nuget --nuget-id=MyLibs --nuget-version=1.0.0

Troubleshooting

Issue	Solution
Package build fails	Check `$VCPKG_ROOT/buildtrees/<pkg>/` for logs
CMake can’t find package	Verify CMAKE_TOOLCHAIN_FILE is set correctly
Version conflict	Use `overrides` in vcpkg.json to pin versions
Triplet mismatch	Ensure `VCPKG_TARGET_TRIPLET` matches in CMake
Old packages after update	Run `vcpkg upgrade --no-dry-run`
Binary cache miss	Check `VCPKG_BINARY_SOURCES` configuration

# Clean buildtrees to free disk space
rm -rf $VCPKG_ROOT/buildtrees/*

# Rebuild a specific package
vcpkg remove zlib && vcpkg install zlib

# Verbose install for debugging
vcpkg install zlib --debug

# Check package info
vcpkg depend-info zlib