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 · CMake overview · build system basics · targets. For other failures, see common 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.

Frequently Asked Questions (FAQ)

Q. When would I use this in practice?

A. Fix CMake Could NOT find Boost and other packages: Config vs Module mode, dev packages on Linux, version constraints.

Q. What should I read before this?

A. Follow the previous article or related articles links at the bottom of each post to learn in sequence. See the C++ series index for the full picture.

Q. Where can I study this more deeply?

A. Check cppreference and the relevant library’s official documentation. The reference links at the end of the article are also worth using.

Other articles related to this topic.

Keywords Covered in This Article (Related Search Terms)

This article covers CMake, find_package, Could NOT find, Build errors, vcpkg, Conan, CMAKE_PREFIX_PATH.