Is vcpkg global per machine?

Usually you clone vcpkg and install per triplet under it; manifest mode improves reproducibility per repo.

CMake cannot find packages?

Ensure CMAKE_TOOLCHAIN_FILE points at vcpkg.cmake; VS vs CLI mismatches are common.

vcpkg and Conan together?

Avoid duplicating the same deps—pick one workflow per project to prevent link/version conflicts.

Slow builds without binary cache?

Source builds take time—use CI caches or binary caching strategies.

vcpkg for C++ | Microsoft Package Manager

2026년 3월 12일 · 16분 읽기 · 수정 2026년 3월 12일 Intermediate tutorial

이 글의 핵심

vcpkg tutorial: install triplets, vcpkg.json manifest, CMAKE_TOOLCHAIN_FILE, CMake integration, binary caching, and CI—compare with Conan for C++ dependency management.

What is vcpkg? why you need it

Problem Scenario: The Pain of Installing Libraries

Problem: To install a C++ library on Windows, you need to download the source from the official site, build it with Visual Studio, and add the header/library path to your project. On Linux it’s easy to install with apt, but on Windows it’s a manual process every time. Solution: vcpkg is a C++ package manager by Microsoft that installs libraries in one line, like ./vcpkg install boost, and automatically integrates with CMake. Windows, Linux, and macOS can all be used with the same command.

// 실행 예제
flowchart LR
    subgraph install[vcpkg install]
        cmd["./vcpkg install fmt"]
    end
    subgraph build[Build]
        download["Download source"]
        compile[compile]
        install_lib[installation]
    end
    subgraph cmake[CMake Integration]
        toolchain[vcpkg.cmake]
        find[find_package(fmt)]
    end
    cmd --> download
    download --> compile
    compile --> install_lib
    install_lib --> toolchain
    toolchain --> find

index

vcpkg installation and basic use
Manifest mode (vcpkg.json)
CMake integration
Version management
Frequently occurring problems and solutions
Production Patterns
Complete example: multi-library project

1. vcpkg installation and basic use

installation

# clone
git clone https://github.com/microsoft/vcpkg
cd vcpkg
# bootstrap
./bootstrap-vcpkg.sh  # Linux/macOS
./bootstrap-vcpkg.bat # Windows
# Add PATH (optional)
export PATH=$PATH:$(pwd)

Basic commands

# Package search
./vcpkg search boost
# Install package
./vcpkg install fmt
./vcpkg install boost-filesystem
# List of installed packages
./vcpkg list
# Remove package
./vcpkg remove fmt
# update
git pull
./bootstrap-vcpkg.sh

Triplet (Build Settings)

# x64 Windows (dynamic link)
./vcpkg install fmt:x64-windows
# x64 Windows (static link)
./vcpkg install fmt:x64-windows-static
# Linux
./vcpkg install fmt:x64-linux
# macOS
./vcpkg install fmt:x64-osx

2. Manifest mode (vcpkg.json)

Create vcpkg.json

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": [
    "fmt",
    "boost-filesystem",
    "spdlog",
    "openssl"
  ]
}

Conditional dependencies

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": [
    "fmt",
    {
      "name": "openssl",
      "platform": "!windows"
    }
  ]
}

features

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "boost",
      "features": ["filesystem", "system"]
    }
  ]
}

3. CMake integration

Method 1: CMAKE_TOOLCHAIN_FILE

# build
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build

Method 2: Environment variables

export VCPKG_ROOT=/path/to/vcpkg
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

Method 3: Include in CMakeLists.txt

# CMakeLists.txt
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
    CACHE STRING "Vcpkg toolchain file")
cmake_minimum_required(VERSION 3.20)
project(MyProject)
find_package(fmt REQUIRED)
find_package(Boost REQUIRED COMPONENTS filesystem)
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE fmt::fmt Boost::filesystem)

4. version control

Specify version in vcpkg.json

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "fmt",
      "version>=": "9.0.0"
    },
    {
      "name": "boost",
      "version>=": "1.78.0"
    }
  ],
  "builtin-baseline": "2023-11-20"
}

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "2023-11-20"
  }
}

5. Frequently occurring problems and solutions

Issue 1: Package build failure

Symptom: Error: Building package boost:x64-windows failed. Cause: Build tools (Visual Studio, GCC, etc.) are missing or have incorrect versions.

# Solution 1: Check build tools
# Windows: Install Visual Studio 2019+
# Linux: Install g++
sudo apt install build-essential
# Solution 2: Check logs
./vcpkg install boost --debug

Issue 2: CMake not finding package

Symptom: find_package(fmt) failed. Cause: CMAKE_TOOLCHAIN_FILE is not specified.

# ❌ Incorrect use
cmake ..
# ✅ Correct use
cmake ...-DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Problem 3: Triplet mismatch

Symptom: Link error (LNK2019, undefined reference). Cause: When installing vcpkg, the triplet and CMake build settings are different.

# Match
./vcpkg install fmt:x64-windows-static
cmake ...-DCMAKE_TOOLCHAIN_FILE=....-DVCPKG_TARGET_TRIPLET=x64-windows-static

Issue 4: Manifest mode not enabled

Symptom: There is vcpkg.json, but it is not automatically installed. Cause: vcpkg does not recognize the manifest when building CMake.

# Solution: Manual installation
./vcpkg install --manifest-root=. --x-install-root=build/vcpkg_installed

6. production pattern

Pattern 1: Include vcpkg as a Git submodule

# Add vcpkg as a submodule
git submodule add https://github.com/microsoft/vcpkg external/vcpkg
git submodule update --init --recursive
# bootstrap
cd external/vcpkg
./bootstrap-vcpkg.sh

# CMakeLists.txt
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/external/vcpkg/scripts/buildsystems/vcpkg.cmake")

Pattern 2: CI/CD integration

# .github/workflows/build.yml
name: Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive
      
      - name: Bootstrap vcpkg
        run: |
          cd external/vcpkg
          ./bootstrap-vcpkg.sh
      
      - name: Install dependencies
        run: |
          ./external/vcpkg/vcpkg install --manifest-root=.
      
      - name: Build
        run: |
          cmake -B build -DCMAKE_TOOLCHAIN_FILE=external/vcpkg/scripts/buildsystems/vcpkg.cmake
          cmake --build build

Pattern 3: Binary caching

# Enable binary cache (reduce build time)
export VCPKG_BINARY_SOURCES="clear;files,/path/to/cache,readwrite"
# or NuGet cache
export VCPKG_BINARY_SOURCES="clear;nuget,https://nuget.company.com,readwrite"

7. Complete example: web server

vcpkg.json

{
  "name": "webserver",
  "version": "1.0.0",
  "dependencies": [
    "boost-asio",
    "boost-beast",
    "fmt",
    "spdlog",
    "nlohmann-json"
  ]
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.20)
project(WebServer VERSION 1.0.0)
set(CMAKE_CXX_STANDARD 20)
find_package(Boost REQUIRED COMPONENTS system)
find_package(fmt REQUIRED)
find_package(spdlog REQUIRED)
find_package(nlohmann_json REQUIRED)
add_executable(webserver
    src/main.cpp
    src/server.cpp
    src/request_handler.cpp
)
target_link_libraries(webserver PRIVATE
    Boost::system
    fmt::fmt
    spdlog::spdlog
    nlohmann_json::nlohmann_json
)

Build

# vcpkg bootstrap (only the first time)
cd vcpkg
./bootstrap-vcpkg.sh
# Build the project
cd ..
cmake -B build -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build -j$(nproc)

organize

concept	Description
vcpkg	Microsoft C++ Package Manager
Manifest Mode	Specify dependencies with `vcpkg.json`
Triplet	Build settings (x64-windows, x64-linux, etc.)
CMAKE_TOOLCHAIN_FILE	CMake integration
Binary Caching	Reduce build time
vcpkg installs C++ libraries with simple commands and automatically integrates with CMake, making cross-platform development easy.

FAQ

Q1: vcpkg vs Conan?

A: vcpkg is simple to use and has good Windows integration. Conan is flexible and easy to build a private server. Choose one that suits your team environment.

Q2: What is manifest mode?

A: If you specify dependencies in vcpkg.json, vcpkg will automatically install them when building CMake. Team members only need to install vcpkg and do not need to run the vcpkg install command separately.

Q3: Why are triplets needed?

A: The same package has different build settings, such as Dynamic/Static Link and Debug/Release. This is specified as a triplet. x64-windows is dynamic linking, x64-windows-static is static linking.

Q4: Where is the vcpkg cache?

A: There are installed packages in vcpkg/installed/ and build intermediate files in vcpkg/buildtrees/. You can clean up old packages with ./vcpkg remove --outdated.

Q5: How about binary caching?

A: By specifying the cache location with the VCPKG_BINARY_SOURCES environment variable, you can significantly reduce build time by reusing built packages. Placing a team shared cache on NuGet or a file server allows all team members to build quickly.

Q6: What are vcpkg learning resources?

vcpkg official document
vcpkg GitHub
vcpkg package list One-line summary: vcpkg makes it easy to install C++ libraries and integrate them into CMake. Next, it would be a good idea to read CMake Guide.

Good article to read together (internal link)

Here’s another article related to this topic.

Practical tips

These are tips that can be applied right away in practice.

Debugging tips

If you run into a problem, check the compiler warnings first.
Reproduce the problem with a simple test case

Performance Tips

Don’t optimize without profiling
Set measurable indicators first

Code review tips

Check in advance for areas that are frequently pointed out in code reviews.
Follow your team’s coding conventions

Practical checklist

This is what you need to check when applying this concept in practice.

Before writing code

Is this technique the best way to solve the current problem?
Can team members understand and maintain this code?
Does it meet the performance requirements?

Writing code

Have you resolved all compiler warnings?
Have you considered edge cases?
Is error handling appropriate?

When reviewing code

Is the intent of the code clear?
Are there enough test cases?
Is it documented? Use this checklist to reduce mistakes and improve code quality.

This article will be helpful if you search for C++, vcpkg, package, library, tools, microsoft, etc.

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

이 글에서 다루는 키워드 (관련 검색어)

C++, vcpkg, Package Manager, CMake, Microsoft, Dependencies 등으로 검색하시면 이 글이 도움이 됩니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.