Previous
Next
CMake “Could NOT find …”: find_package Failures,

CMake “Could NOT find …”: find_package Failures,

· 17분 읽기 · 수정 Intermediate Problem-solving
CMake “Could NOT find …”: find_package Failures,

이 글의 핵심

Fix CMake Could NOT find Boost and other packages: Config vs Module mode, dev packages on Linux, version constraints, COMPONENTS, case sensitivity, and package managers.

CMake guides: [find_package](/en/blog/cpp-cmake-find-package/ · [CMake overview](/en/blog/cpp-cmake/ · [build system basics](/en/blog/cpp-cmake-build-system/ · [targets](/en/blog/cpp-cmake-targets/. For other failures, see [common CMake errors](/en/blog/cpp-error-18-cmake-errors/.

Introduction: “Could NOT find Boost (missing: …)”

You called find_package(Boost REQUIRED) and CMake stopped with Could NOT find Boost or missing variables. The library may be installed—but CMake cannot locate its CMake package files or the compiled components you need. This article covers:

  • Config vs Module search
  • Five frequent causes: not installed, wrong path, version, missing Config, case, missing COMPONENTS
  • CMAKE_PREFIX_PATH
  • vcpkg and Conan
flowchart TD
  A[find_package fails] --> B[Installed?]
  B --> C[Config/Module path]
  C --> D[CMAKE_PREFIX_PATH]
  D --> E[Version & components]
  E --> F[vcpkg / Conan]

Table of contents

  1. How find_package works
  2. Cause 1: not installed / wrong path
  3. Cause 2: version mismatch
  4. Cause 3: no Config (Module fallback fails)
  5. Cause 4: package name case
  6. Cause 5: missing COMPONENTS
  7. CMAKE_PREFIX_PATH
  8. Package managers

1. How find_package works

Config mode (preferred when available): loads FooConfig.cmake (or similar) shipped with the library—defines imported targets like Boost::system. Module mode: uses CMake’s FindFoo.cmake—works for many common libs but can lag or guess wrong paths. Search locations include CMAKE_PREFIX_PATH, Foo_DIR, and system prefixes.

2. Not installed / path

Linux: runtime-only packages lack headers—install -dev / lib-all-dev* metapackages when needed.

ls /usr/include/boost/
ls /usr/lib/x86_64-linux-gnu/libboost_system*

macOS: brew install boost then often set:

export CMAKE_PREFIX_PATH="$(brew --prefix boost)"

3. Version mismatch

find_package(Boost 1.75 REQUIRED)

If only 1.71 is installed, either lower the requirement, upgrade Boost, or find_package(Boost REQUIRED) without a hard minimum if acceptable.

4. No Config / Module fails

Point CMake at the config directory:

set(MyLib_DIR "/path/to/lib/cmake/MyLib")
find_package(MyLib REQUIRED)

Or fall back to find_library / find_path and target_include_directories + target_link_libraries.

5. Case sensitivity

On Linux/macOS, find_package(boost) may fail where find_package(Boost) succeeds—match the exact package name from upstream docs.

6. COMPONENTS (Boost example)

Header-only parts need no link, but Boost.System, Boost.Filesystem, etc. need compiled libs:

find_package(Boost REQUIRED COMPONENTS system filesystem)
target_link_libraries(myapp PRIVATE Boost::system Boost::filesystem)

7. CMAKE_PREFIX_PATH

cmake -DCMAKE_PREFIX_PATH=/opt/mylibs ..
list(APPEND CMAKE_PREFIX_PATH "/opt/mylibs")
find_package(MyLib REQUIRED)

8. vcpkg & Conan

vcpkg (toolchain-driven):

cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake ..

Conan (CMakeDeps/CMakeToolchain):

conan install . --build=missing
cmake --preset conan-default

Debugging workflow

  1. Read which variables are “missing” in the error.
  2. Confirm dev packages / vcpkg packages installed.
  3. Locate *Config.cmake.
  4. Set CMAKE_PREFIX_PATH or -DFoo_DIR=….
  5. Run cmake —debug-find .. to print search traces.

Summary table

SymptomAction
Headers missingInstall -dev / use vcpkg
Wrong pathCMAKE_PREFIX_PATH
VersionRelax requirement or upgrade
No Configfind_library fallback
CaseMatch find_package spelling
Link still failsAdd COMPONENTS + target_link_libraries

Keywords

CMake Could NOT find, find_package, CMAKE_PREFIX_PATH, vcpkg toolchain, Boost Config.cmake

Closing: Could NOT find almost always means CMake cannot see the package root—set CMAKE_PREFIX_PATH, install dev artifacts, specify COMPONENTS, and prefer vcpkg/Conan for repeatable Windows/Linux/macOS workflows.

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. Fix CMake Could NOT find Boost and other packages: Config vs Module mode, dev packages on Linux, version constraints, CO… 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 또는 관련 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

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

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

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

CMake, find_package, Could NOT find, Build errors, vcpkg, Conan, CMAKE_PREFIX_PATH 등으로 검색하시면 이 글이 도움이 됩니다.