Fix CMake "Could NOT Find a Package" — and When FetchContent Is the Right Fallback
The library is installed. Its config file is on disk, in the standard folder. Configure still fails, because find_package never searched the prefix the library was installed to — and the error, read closely, says exactly that and names both fixes. This guide builds a small Greet library, installs it to a local prefix with a proper package config file, reproduces the failure against a program that links it, and fixes the search two native ways. It then builds the case those fixes cannot help — a library that ships no config file at all — and brings it in with FetchContent instead.
Written November 19, 2026 · Tested with CMake 3.28.3 · 14 min read
- The package is installed, and configure still fails
- Reading the error line by line
- Fix one: add the prefix to CMAKEPREFIXPATH
- Fix two: set GreetDIR to the config file's directory
What this guide is
One configure error covers two different problems, and they have different fixes. The examples here use CMake 3.28.3 and GCC 13.3.0. In the first problem the package exists as an install — a library, a header, and a package configuration file — but the consuming project never told CMake where that install lives, so the search missed it. In the second problem there is no install and no configuration file anywhere: the library exists only as sources, and no search path can find a file that does not exist. The first problem is fixed by pointing the search at the prefix. The second is what FetchContent is for.
The package is installed, and configure still fails
The library is one header and one source file:
// greet.h
#pragma once
void greet();
// greet.cpp
#include "greet.h"
#include <iostream>
void greet() { std::cout << "hello from greet\n"; }
Its build file builds the library and installs it as a package — the archive, the header, an exported target file, and a configuration file that loads that export:
cmake_minimum_required(VERSION 3.28)
project(Greet CXX)
add_library(Greet greet.cpp)
add_library(Greet::Greet ALIAS Greet)
target_include_directories(Greet PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
$<INSTALL_INTERFACE:include>)
install(TARGETS Greet EXPORT GreetTargets ARCHIVE DESTINATION lib)
install(FILES greet.h DESTINATION include)
install(EXPORT GreetTargets FILE GreetTargets.cmake NAMESPACE Greet::
DESTINATION lib/cmake/Greet)
configure_file(GreetConfig.cmake.in GreetConfig.cmake @ONLY)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/GreetConfig.cmake
DESTINATION lib/cmake/Greet)
The configuration file itself is one line — it loads the exported targets, which is what makes the imported target Greet::Greet available to a consumer:
# GreetConfig.cmake.in
include("${CMAKE_CURRENT_LIST_DIR}/GreetTargets.cmake")
Build the library and install it to a prefix next to the library's folder:
$ cmake -S . -B build -DCMAKE_INSTALL_PREFIX=../prefix
$ cmake --build build
$ cmake --install build
The prefix now holds the whole package, configuration file included:
$ find prefix -type f | sort
prefix/include/greet.h
prefix/lib/cmake/Greet/GreetConfig.cmake
prefix/lib/cmake/Greet/GreetTargets-noconfig.cmake
prefix/lib/cmake/Greet/GreetTargets.cmake
prefix/lib/libGreet.a
The consuming program is a single main.cpp that calls greet(), and its build file asks for the package by name:
cmake_minimum_required(VERSION 3.28)
project(app CXX)
find_package(Greet REQUIRED)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE Greet::Greet)
Configure it from its own folder, with no hint about the prefix, and configure fails:
$ cmake -S . -B build
CMake Error at CMakeLists.txt:3 (find_package):
By not providing "FindGreet.cmake" in CMAKE_MODULE_PATH this project has
asked CMake to find a package configuration file provided by "Greet", but
CMake did not find one.
Could not find a package configuration file provided by "Greet" with any of
the following names:
GreetConfig.cmake
greet-config.cmake
Add the installation prefix of "Greet" to CMAKE_PREFIX_PATH or set
"Greet_DIR" to a directory containing one of the above files. If "Greet"
provides a separate development package or SDK, be sure it has been
installed.
-- Configuring incomplete, errors occurred!
Nothing in that output says the package is missing. It says the search did not find it — a different claim, and the next section reads the difference.
Reading the error line by line
The first paragraph is about module mode. find_package searches in two modes. In module mode it looks for a file named Find<PackageName>.cmake, first in the locations listed in CMAKE_MODULE_PATH, then among the Find modules that ship with CMake itself. That file is not normally provided by the package; it is provided by something external to it, such as the operating system or CMake. No FindGreet.cmake exists in either place for this library, so the paragraph reports that route closed — it is not the failure itself, just the first route tried.
The middle paragraph is config mode, and it is the substance of the error. In config mode CMake searches for a file called <PackageName>Config.cmake or <lowercasePackageName>-config.cmake — here, GreetConfig.cmake or greet-config.cmake. Those files are typically installed as part of the package, which is why they tend to be more reliable than Find modules: the file knows the package's own contents. Under each installation prefix it searches, CMake looks in a set of conventional subdirectories for the configuration file — on a UNIX-style layout, entries such as <prefix>/lib/cmake/<name>*/ among them. The installed file sits at exactly such a place, prefix/lib/cmake/Greet/GreetConfig.cmake. It was never seen, because the prefix itself was never among the prefixes searched: the default search covers system prefixes, and a private install prefix next to the project is not one of them.
The last paragraph is the remedy, and it names both native fixes in one sentence: add the installation prefix to CMAKE_PREFIX_PATH, or set Greet_DIR to the directory containing one of the configuration files. A cache entry called <PackageName>_DIR is created to hold the directory containing the configuration file once one is found, and pointing it there directly skips the prefix search for that package. The closing sentence — be sure a separate development package has been installed — is the one branch this example does not hit: the file listing above shows the configuration file already installed.
One more line decides how hard this failure lands. The call above passes REQUIRED, and the REQUIRED option stops processing with an error message if the package cannot be found. Drop REQUIRED and the same miss becomes a warning with the same body, and the variable Greet_FOUND is set to 0 for the project to test. A project that treats the package as optional has to test that variable and link only when it is set — the build file above links Greet::Greet unconditionally, so in that file the miss would surface one step later, at the generate step, when the link names a target that was never created. The optional form of the build file looks like this:
cmake_minimum_required(VERSION 3.28)
project(app CXX)
find_package(Greet)
message(STATUS "Greet_FOUND=${Greet_FOUND}")
add_executable(app main.cpp)
Configure that file, with no hint about the prefix, and the miss arrives as a warning:
$ cmake -S . -B build
CMake Warning at CMakeLists.txt:3 (find_package):
By not providing "FindGreet.cmake" in CMAKE_MODULE_PATH this project has
asked CMake to find a package configuration file provided by "Greet", but
CMake did not find one.
Could not find a package configuration file provided by "Greet" with any of
the following names:
GreetConfig.cmake
greet-config.cmake
Add the installation prefix of "Greet" to CMAKE_PREFIX_PATH or set
"Greet_DIR" to a directory containing one of the above files. If "Greet"
provides a separate development package or SDK, be sure it has been
installed.
-- Greet_FOUND=0
With that build file — no REQUIRED, the _FOUND value printed instead of assumed, and no unconditional link to the missing target — the same miss is a warning, configure completes, and the printed line reports the result. So a Could NOT find failure with REQUIRED and a silent misconfiguration without it are the same search miss at two severities. When a project configures but then fails to link a library it expected, a non-required find_package that quietly set its _FOUND variable to 0 is a place to look.
Fix one: add the prefix to CMAKE_PREFIX_PATH
CMAKE_PREFIX_PATH is a semicolon-separated list of directories specifying installation prefixes to be searched by the find_package, find_program, find_library, find_file, and find_path commands, and each command adds the appropriate subdirectories for what it is looking for. Give it the prefix the library was installed to, in a fresh build directory:
$ cmake -S . -B build -DCMAKE_PREFIX_PATH=../prefix
$ cmake --build build
[ 50%] Building CXX object CMakeFiles/app.dir/main.cpp.o
[100%] Linking CXX executable app
[100%] Built target app
$ ./build/app
hello from greet
The build compiles only main.cpp: the library arrives prebuilt through the imported target Greet::Greet, which the configuration file loaded. That is the shape of a successful package consume — the consumer builds its own sources and links the package's archive, headers, and usage requirements as one target. The same prefix can also arrive through the CMAKE_PREFIX_PATH environment variable of the same name, which is used as an additional list of search prefixes; the -D form is the one that lands in the cache and shows up in the project's own configuration, so it is the form to leave in build instructions.
Fix two: set Greet_DIR to the config file's directory
The second native fix names the file's folder instead of the prefix. Greet_DIR takes the directory containing GreetConfig.cmake — not the prefix, and not the file itself:
$ cmake -S . -B build -DGreet_DIR=../prefix/lib/cmake/Greet
$ cmake --build build
[ 50%] Building CXX object CMakeFiles/app.dir/main.cpp.o
[100%] Linking CXX executable app
[100%] Built target app
$ ./build/app
hello from greet
The two fixes reach the same file by different routes, and they suit different situations. CMAKE_PREFIX_PATH is the general route: one prefix can serve every package installed under it, and it is the right default when a project consumes several packages from one install tree or one SDK root. <PackageName>_DIR is the surgical route: it names one package's configuration directory exactly, and it is the right tool when two prefixes hold different builds of the same package and the choice between them has to be explicit. If <PackageName>_DIR has been set to a directory not containing a configuration file, CMake ignores it and searches from scratch — so a stale Greet_DIR left in a cache does not block the prefix route, but it also does not announce itself; when a fix seems to have no effect, reading the cached Greet_DIR value is the check.
Forcing config mode states which route a project means. With the CONFIG keyword, the module-mode paragraph disappears from the error entirely, because no Find module was ever sought:
$ cmake -S . -B build
CMake Error at CMakeLists.txt:3 (find_package):
Could not find a package configuration file provided by "Greet" with any of
the following names:
GreetConfig.cmake
greet-config.cmake
Add the installation prefix of "Greet" to CMAKE_PREFIX_PATH or set
"Greet_DIR" to a directory containing one of the above files. If "Greet"
provides a separate development package or SDK, be sure it has been
installed.
-- Configuring incomplete, errors occurred!
The FetchContent fallback: when there is no config file at all
Both native fixes presuppose a configuration file exists somewhere to be found. The second problem is the library that has none. A source-only copy of the same library — same header, same source, a build file that defines a plain target and installs nothing, and no configuration file anywhere — cannot be found by find_package under any prefix, because there is no GreetConfig.cmake to find:
cmake_minimum_required(VERSION 3.28)
project(GreetSrc CXX)
add_library(greet greet.cpp)
target_include_directories(greet PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
For that case the dependency is brought into the build instead of being searched for. The FetchContent module declares where the content comes from and then makes it available: FetchContent_Declare records the details for a dependency, and FetchContent_MakeAvailable ensures the named dependencies have been populated and adds them to the main build, so the main build can use the populated projects' targets. Here the content is a local source directory, named with the SOURCE_DIR option:
cmake_minimum_required(VERSION 3.28)
project(app_fetch CXX)
include(FetchContent)
FetchContent_Declare(greet_src
SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../greet_src)
FetchContent_MakeAvailable(greet_src)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE greet)
Configure, build, and run:
$ cmake -S . -B build
$ cmake --build build
[ 25%] Building CXX object _deps/greet_src-build/CMakeFiles/greet.dir/greet.cpp.o
[ 50%] Linking CXX static library libgreet.a
[ 50%] Built target greet
[ 75%] Building CXX object CMakeFiles/app.dir/main.cpp.o
[100%] Linking CXX executable app
[100%] Built target app
$ ./build/app
hello from greet
Read the build lines against the package consume above and the mechanism difference is visible. The library's own source compiles inside the consumer's build tree, under the _deps/greet_src-build folder FetchContent populates the content into, and the target linked is the plain greet target the dependency's own build file defines — available to target_link_libraries as soon as FetchContent_MakeAvailable returns. There is no imported target and no configuration file, because nothing was installed.
In real use, the declared content usually comes from a git repository or a URL archive rather than a folder on disk, and the declaration names that origin instead of SOURCE_DIR. The mechanism after the declaration is the same either way: the content is populated, its top-level build file is added to the build, and its targets are available to link. The local folder in this example keeps every step visible in the build output, with nothing fetched.
FetchContent is the fallback, not the default, and the order matters. A package that ships a configuration file gives the consumer the package's own statement of its targets, its version handling, and its usage requirements, built and installed once and shared by every consumer. FetchContent rebuilds the dependency inside each consumer, at the version the declaration pins, and makes the consumer's build responsible for it. That trade is worth making when there is no configuration file to find — a source-only library, a dependency whose install is broken, or a version that must be pinned inside the project — and it is a step backwards when a working install already exists and only the search path was missing.
Which fix for which cause
| What configure prints or does | Cause | Fix |
|---|---|---|
| Could not find a configuration file; the package sits in a non-system prefix | The prefix was never searched | Add the prefix via CMAKE_PREFIX_PATH; reconfigure fresh |
| Could not find a configuration file; one package must come from one place | The search needs the exact configuration directory | Set <PackageName>_DIR to that directory |
| The same text as a warning; the feature is silently off | No REQUIRED, so the miss set _FOUND to 0 and processing continued |
Fix the search as above; test _FOUND for optional packages |
| A Find-module paragraph leads the error | Module mode was tried first; no Find module exists | Read past it to the config-mode paragraph; fix the search path |
| No configuration file exists; the library ships sources only | Nothing for find_package to find, at any prefix |
Bring the sources in with FetchContent; link its target |
| A working install exists, and FetchContent is in use for it | The fallback was applied to the first problem | Prefer the installed package; keep FetchContent for source-only dependencies |
Checklist
- Before changing anything, check whether the configuration file exists on disk, and where. A file at
<prefix>/lib/cmake/<PackageName>/that configure cannot see is a search problem, not an install problem. - Before reinstalling a package, read the error's last paragraph: it names the two variables that fix the search,
CMAKE_PREFIX_PATHand<PackageName>_DIR. - Before setting
<PackageName>_DIR, confirm the value is the directory containing the configuration file — not the prefix, and not the file itself. - Before trusting a configure that succeeded, check any non-required
find_packageresults: a miss withoutREQUIREDis a warning plus a_FOUNDvariable set to0, not a failure. - Before reaching for FetchContent, look for the configuration file. If one exists, the native fix is shorter and the installed package stays shared; FetchContent is for the package that has no config file.
- Before pinning a dependency with FetchContent, note what the trade is: the dependency rebuilds inside every consumer, and its targets come from its own build file, not from an imported package target.
Related guides on this site
- Fix CMake "Cannot Find Source File" and "No SOURCES Given to Target" — the sibling configure failure: a listed source name and a file on disk that have stopped agreeing.
- CMake Presets, vcpkg, and Modules: Decisions — the configuration-layer choices around dependency handling, once the search itself works.
- C++20 Header-Only Modules with CMake Install — the install side from the package author's chair: the rules that put a config file where consumers search for it.
- C++20 Modules with CMake and Ninja — a full CMake project built end to end, for projects that grow past a single dependency.
Sources
- CMake, find_package — module mode searches for a
Find<PackageName>.cmakefile, config mode searches for<PackageName>Config.cmakeor<lowercasePackageName>-config.cmakeunder each searched prefix, a cache entry called<PackageName>_DIRholds the directory containing the configuration file, and theREQUIREDoption stops processing with an error if the package cannot be found. - CMake, CMAKE_PREFIX_PATH — the semicolon-separated list of installation prefixes searched by the
find_package,find_program,find_library,find_file, andfind_pathcommands, with an environment variable of the same name used as an additional list of search prefixes. - CMake, FetchContent —
FetchContent_Declarerecords how to populate a dependency,FetchContent_MakeAvailableensures the named dependencies have been populated and adds them to the main build so the main build can use the populated projects' targets, andFETCHCONTENT_SOURCE_DIR_<uppercaseName>can override the declared details to use content at a specified location. - CMake, CMake Packages — how packages provide configuration files for consumers, and the package file interface a configuration file uses.
Keep Exploring
Seven tips and seven puzzles so far, each one a short runnable example with the fix explained.
Paste an AddressSanitizer, UBSan, or ThreadSanitizer report and get the bug, the file and line, and the fix \u2014 in plain language.
C++20 and C++23 features, migration paths, and measured trade-offs.
The full C++ hub \u2014 language basics, the standard library, coroutines, and measured comparisons.
Paste a [Service] section and get a plain-language verdict on every sandboxing setting it finds.