CMake “Could NOT find …”: find_package Failures, CMAKE_PREFIX_PATH, vcpkg & Conan

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)

Without COMPONENTS, you may get headers but LNK2019 at link time.

---

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

Symptom	Action
Headers missing	Install -dev / use vcpkg
Wrong path	CMAKE_PREFIX_PATH
Version	Relax requirement or upgrade
No Config	find_library fallback
Case	Match find_package spelling
Link still fails	Add COMPONENTS + target_link_libraries

---

Related posts (internal)

• CMake intro
• Package managers
• LNK2019

---

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.