CMake "Could NOT find" 에러

· 17분 읽기 · 수정
CMake "Could NOT find" 에러

이 글의 핵심

Could NOT find (missing: ...) 에러 해결. find_package 실패 원인(경로, 버전, Config vs Module), CMAKE_PREFIX_PATH 설정, vcpkg·Conan 활용법.

들어가며: “Could NOT find Boost (missing: …)”

CMake로 외부 라이브러리를 쓰려고 find_package(Boost REQUIRED)를 호출했는데, Could NOT find Boost (missing: Boost_INCLUDE_DIR Boost_LIBRARY_DIRS) 같은 에러가 나는 경우가 많습니다. “find_package 실패”, “Could NOT find”, “CMAKE_PREFIX_PATH”로 검색해 오셨다면 이 글이 도움이 됩니다. 라이브러리는 분명 설치했는데 CMake가 찾지 못하는 상황입니다. 이 글은 find_package 실패의 주요 원인 5가지와 환경별 해결법을 정리합니다.

이 글에서 다루는 것:

  • find_package가 어떻게 라이브러리를 찾는지 (Config vs Module 모드)
  • 5가지 주요 원인: 경로 문제, 버전 불일치, Config 파일 없음, 대소문자, 컴포넌트 누락
  • CMAKE_PREFIX_PATH 설정으로 경로 지정하기
  • 패키지 매니저(vcpkg, Conan) 활용법

find_package 실패 시 점검 순서를 요약하면 아래와 같습니다.

flowchart TD
  A[find_package 실패] --> B[라이브러리 설치 여부]
  B --> C[Config/Module 경로]
  C --> D[CMAKE_PREFIX_PATH]
  D --> E[버전·컴포넌트]
  E --> F[vcpkg/Conan 사용]

목차

  1. find_package는 어떻게 찾나요?
  2. 원인 1: 라이브러리가 설치 안 됨 또는 경로 문제
  3. 원인 2: 버전 불일치
  4. 원인 3: Config 파일이 없음 (Module 모드 실패)
  5. 원인 4: 패키지 이름 대소문자 불일치
  6. 원인 5: 필요한 컴포넌트 누락
  7. CMAKE_PREFIX_PATH로 경로 지정
  8. 패키지 매니저 활용 (vcpkg, Conan)

1. find_package는 어떻게 찾나요?

Config 모드 vs Module 모드

find_package(PackageName)는 두 가지 모드로 작동합니다.

Config 모드 (우선):

  • 라이브러리가 제공하는 PackageNameConfig.cmake 또는 packagename-config.cmake 파일을 찾습니다.
  • 이 파일은 보통 라이브러리 설치 시 /usr/local/lib/cmake/PackageName/ 같은 곳에 생성됩니다.
  • 최신 라이브러리는 대부분 Config 파일을 제공합니다.

Config 파일의 역할:
Config 파일은 라이브러리가 직접 제공하는 “사용 설명서”입니다. 헤더 경로, 라이브러리 파일 경로, 컴파일 옵션 등을 정의합니다. CMake는 이 파일을 읽어서 자동으로 Boost::system 같은 타겟(Target)을 생성하고, target_link_libraries만 하면 모든 설정이 자동으로 적용됩니다.

Module 모드 (Config 실패 시):

  • CMake가 제공하는 FindPackageName.cmake 모듈을 찾습니다.
  • CMake 설치 경로의 Modules/ 디렉터리에 있습니다 (예: FindBoost.cmake).
  • 오래된 라이브러리나 CMake가 직접 지원하는 패키지만 해당됩니다.

Module 모드의 한계:
Module 파일은 CMake 개발자가 작성한 것이므로, 라이브러리 버전이 바뀌면 업데이트가 늦을 수 있습니다. 또한 라이브러리 설치 경로를 추측해서 찾으므로, 비표준 경로에 설치하면 실패할 가능성이 높습니다. 최신 라이브러리는 대부분 Config 모드를 권장합니다.

검색 경로

CMake는 다음 경로에서 Config/Module 파일을 찾습니다.

  1. CMAKE_PREFIX_PATH 환경 변수 또는 CMake 변수
  2. 시스템 기본 경로: /usr/local/, /usr/, C:/Program Files/ 등
  3. PackageName_DIR 변수 (직접 지정 가능)

2. 원인 1: 라이브러리가 설치 안 됨 또는 경로 문제

문제 상황

find_package(Boost REQUIRED)

에러:

CMake Error at CMakeLists.txt:5 (find_package):
  Could NOT find Boost (missing: Boost_INCLUDE_DIR Boost_LIBRARY_DIRS)

원인: Boost가 설치되지 않았거나, CMake가 찾는 경로에 없습니다.

가장 흔한 케이스:
라이브러리를 설치했다고 생각했는데, 실제로는 헤더만 설치되고 라이브러리 파일(.so, .lib)은 없는 경우입니다. 또는 개발 패키지(dev package)를 설치하지 않은 경우입니다.

Linux 예시:

  • sudo apt install boost → ❌ 런타임 라이브러리만 설치
  • sudo apt install libboost-all-dev → ✅ 헤더 + 라이브러리 + Config 파일

확인 방법:

# 헤더 파일 확인
ls /usr/include/boost/

# 라이브러리 파일 확인
ls /usr/lib/x86_64-linux-gnu/libboost_system*

헤더는 있는데 라이브러리가 없으면, dev 패키지를 설치해야 합니다.

해결법 1: 라이브러리 설치

Ubuntu/Debian:

sudo apt install libboost-all-dev

macOS (Homebrew):

brew install boost

Windows: Boost 공식 사이트에서 다운로드하거나, vcpkg 사용 (아래 섹션 참고).

해결법 2: CMAKE_PREFIX_PATH 설정

라이브러리를 비표준 경로에 설치했다면, CMake에 경로를 알려 줘야 합니다.

CMakeLists.txt:

set(CMAKE_PREFIX_PATH "/opt/mylibs;${CMAKE_PREFIX_PATH}")
find_package(Boost REQUIRED)

명령줄:

cmake -DCMAKE_PREFIX_PATH=/opt/mylibs ..

환경 변수:

export CMAKE_PREFIX_PATH=/opt/mylibs:$CMAKE_PREFIX_PATH
cmake ..

3. 원인 2: 버전 불일치

문제 상황

find_package(Boost 1.75 REQUIRED)

에러:

Could NOT find Boost (missing: Boost_INCLUDE_DIR) (found suitable version "1.71.0", minimum required is "1.75")

원인: 설치된 Boost 버전(1.71)이 요구 버전(1.75)보다 낮습니다.

해결법

1. 버전 요구사항 낮추기:

find_package(Boost 1.71 REQUIRED)  # ✅ 설치된 버전에 맞춤

2. 최신 버전 설치:

# Ubuntu
sudo apt install libboost-all-dev

# macOS
brew upgrade boost

3. 버전 지정 제거 (최소 버전만 요구):

find_package(Boost REQUIRED)  # 버전 제약 없음

4. 원인 3: Config 파일이 없음 (Module 모드 실패)

문제 상황

최신 라이브러리인데 CMake가 FindXXX.cmake 모듈을 제공하지 않고, 라이브러리도 Config 파일을 생성하지 않은 경우입니다.

find_package(MyLib REQUIRED)

에러:

Could NOT find MyLib (missing: MyLib_DIR)

해결법 1: Config 파일 경로 직접 지정

라이브러리를 빌드·설치할 때 **MyLibConfig.cmake**가 생성되었다면, 그 경로를 지정합니다.

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

또는 명령줄:

cmake -DMyLib_DIR=/path/to/mylib/lib/cmake/MyLib ..

해결법 2: find_library로 직접 찾기

find_package를 포기하고, find_library로 .a/.so/.lib 파일을 직접 찾습니다.

find_library(MYLIB_LIBRARY NAMES mylib PATHS /usr/local/lib)
find_path(MYLIB_INCLUDE_DIR NAMES mylib/api.h PATHS /usr/local/include)

if(NOT MYLIB_LIBRARY OR NOT MYLIB_INCLUDE_DIR)
    message(FATAL_ERROR "MyLib not found")
endif()

add_executable(myapp main.cpp)
target_include_directories(myapp PRIVATE ${MYLIB_INCLUDE_DIR})
target_link_libraries(myapp PRIVATE ${MYLIB_LIBRARY})

5. 원인 4: 패키지 이름 대소문자 불일치

문제 상황

find_package(boost REQUIRED)  # ❌ 소문자

에러:

Could NOT find boost

원인: Config 파일 이름이 BoostConfig.cmake인데, find_package(boost)로 소문자로 찾으면 실패할 수 있습니다. Linux/macOS는 대소문자를 구분합니다.

해결법

정확한 대소문자 사용:

find_package(Boost REQUIRED)  # ✅ 대문자 B

라이브러리 문서에서 정확한 패키지 이름을 확인하세요.

6. 원인 5: 필요한 컴포넌트 누락

문제 상황

find_package(Boost REQUIRED)

에러:

Could NOT find Boost (missing: system filesystem)

원인: Boost는 여러 컴포넌트로 나뉘어 있습니다. COMPONENTS를 지정하지 않으면 헤더만 찾고, 필요한 라이브러리(.so/.lib)를 찾지 못합니다.

Boost의 구조:
Boost는 100개 이상의 라이브러리로 구성되어 있습니다. 일부는 헤더 온리(Header-only)라서 링크가 필요 없지만(예: Boost.Algorithm), 일부는 컴파일된 라이브러리가 필요합니다(예: Boost.System, Boost.Filesystem).

헤더 온리 vs 컴파일 필요:

  • 헤더 온리: #include만 하면 됨 (예: <boost/algorithm/string.hpp>)
  • 컴파일 필요: 별도 .lib/.so 파일 링크 필요 (예: boost_system.lib)

COMPONENTS를 지정하지 않으면, CMake는 헤더만 찾고 끝입니다. 컴파일된 라이브러리가 필요한 함수를 쓰면 LNK2019 에러가 발생합니다.

해결법

필요한 컴포넌트 명시:

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

주의: 컴포넌트 이름은 라이브러리마다 다릅니다. 문서를 확인하세요.

7. CMAKE_PREFIX_PATH로 경로 지정

여러 경로 추가

list(APPEND CMAKE_PREFIX_PATH 
    "/opt/mylibs"
    "/usr/local/custom"
)
find_package(MyLib REQUIRED)

환경 변수로 설정

export CMAKE_PREFIX_PATH=/opt/mylibs:/usr/local/custom
cmake ..

Windows에서

set CMAKE_PREFIX_PATH=C:\libs;C:\custom
cmake ..

또는 CMake GUI에서 CMAKE_PREFIX_PATH 변수를 추가합니다.

8. 패키지 매니저 활용 (vcpkg, Conan)

vcpkg (Microsoft)

vcpkg는 C++ 라이브러리를 자동으로 다운로드·빌드·설치하고, CMake에서 바로 쓸 수 있게 해 줍니다.

vcpkg의 장점:

  • 크로스 플랫폼: Windows, Linux, macOS 모두 지원
  • 자동 빌드: 소스에서 자동으로 빌드해서 설치
  • CMake 통합: toolchain 파일 하나로 모든 라이브러리 자동 인식
  • 버전 관리: vcpkg.json으로 프로젝트별 의존성 관리

언제 쓰나요?
특히 Windows 환경에서 C++ 라이브러리 관리가 어려운데, vcpkg는 이를 npm/pip처럼 쉽게 만들어 줍니다. Linux/macOS는 시스템 패키지 매니저(apt, brew)가 있지만, Windows는 vcpkg가 사실상 표준입니다.

설치:

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # Linux/macOS
# 또는 bootstrap-vcpkg.bat (Windows)

라이브러리 설치:

./vcpkg install boost
./vcpkg install fmt
./vcpkg install nlohmann-json

CMake에서 사용:

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

이후 find_package(Boost REQUIRED)가 자동으로 작동합니다.

CMakeLists.txt:

find_package(Boost REQUIRED COMPONENTS system)
find_package(fmt REQUIRED)
find_package(nlohmann_json REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE 
    Boost::system 
    fmt::fmt 
    nlohmann_json::nlohmann_json
)

Conan

Conan도 비슷하게 작동합니다.

conanfile.txt:

[requires]
boost/1.80.0
fmt/9.1.0

[generators]
CMakeDeps
CMakeToolchain

빌드:

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

해결 체크리스트

원인확인 사항해결법
라이브러리 미설치apt search, brew search패키지 매니저로 설치
경로 문제Config 파일 위치 확인CMAKE_PREFIX_PATH 설정
버전 불일치설치된 버전 vs 요구 버전버전 낮추거나 업그레이드
Config 파일 없음XXXConfig.cmake 존재 여부find_library로 직접 찾기
대소문자 오류패키지 이름 확인정확한 이름 사용
컴포넌트 누락COMPONENTS 지정필요한 컴포넌트 명시

실전 디버깅 프로세스

1단계: 에러 메시지 확인

Could NOT find Boost (missing: Boost_INCLUDE_DIR)

→ Boost_INCLUDE_DIR를 찾지 못했다는 뜻. 헤더 경로 문제입니다.

2단계: 라이브러리 설치 확인

# Ubuntu/Debian
dpkg -l | grep boost

# macOS
brew list | grep boost

# Windows
vcpkg list | findstr boost

3단계: Config 파일 찾기

find /usr -name "BoostConfig.cmake" 2>/dev/null
find /usr/local -name "boost-config.cmake" 2>/dev/null

4단계: CMAKE_PREFIX_PATH 설정

Config 파일이 /opt/boost/lib/cmake/Boost/에 있다면:

cmake -DCMAKE_PREFIX_PATH=/opt/boost ..

5단계: 디버그 모드로 재실행

cmake --debug-find ..

--debug-find를 쓰면 CMake가 어디를 검색했는지 자세히 출력합니다.

환경별 자주 하는 실수

Linux

문제: sudo apt install boost로 설치했는데 못 찾음.
원인: 패키지 이름이 libboost-all-dev입니다.
해결: sudo apt install libboost-all-dev

macOS (Homebrew)

문제: brew install boost 후에도 못 찾음.
원인: Homebrew는 /usr/local/ 또는 /opt/homebrew/에 설치하는데, CMake가 못 찾을 수 있습니다.
해결:

export CMAKE_PREFIX_PATH=/opt/homebrew
cmake ..

또는:

brew --prefix boost
# 출력: /opt/homebrew/opt/boost
cmake -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/boost ..

Windows (수동 설치)

문제: Boost를 C:\boost에 압축 풀었는데 못 찾음.
원인: Config 파일이 없거나, 경로를 지정하지 않음.
해결:

cmake -DBOOST_ROOT=C:\boost -DBoost_INCLUDE_DIR=C:\boost\include ..

또는 vcpkg 사용:

vcpkg install boost
cmake -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake ..

vcpkg 실전 예시

설치 및 설정

# vcpkg 설치
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh

# 라이브러리 설치
./vcpkg install boost-system boost-filesystem
./vcpkg install fmt

CMakeLists.txt

cmake_minimum_required(VERSION 3.15)
project(MyApp LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# vcpkg toolchain을 쓰면 find_package가 자동으로 작동
find_package(Boost REQUIRED COMPONENTS system filesystem)
find_package(fmt REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE 
    Boost::system 
    Boost::filesystem 
    fmt::fmt
)

빌드

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

팁: vcpkg toolchain 파일을 환경 변수로 설정해 두면 매번 지정하지 않아도 됩니다.

export CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Conan 실전 예시

conanfile.txt 작성

[requires]
boost/1.80.0
fmt/9.1.0

[generators]
CMakeDeps
CMakeToolchain

[options]
boost:shared=False

설치 및 빌드

# 의존성 설치
conan install . --build=missing

# CMake 빌드 (Conan이 생성한 preset 사용)
cmake --preset conan-default
cmake --build --preset conan-release

CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(MyApp LANGUAGES CXX)

find_package(Boost REQUIRED)
find_package(fmt REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE Boost::Boost fmt::fmt)

정리: find_package 실패 시 순서대로 체크

  1. 라이브러리 설치 확인 → apt search, brew list, vcpkg list
  2. Config 파일 위치 찾기 → find / -name "XXXConfig.cmake"
  3. CMAKE_PREFIX_PATH 설정 → Config 파일이 있는 상위 디렉터리 지정
  4. 버전 확인 → 요구 버전과 설치된 버전 비교
  5. 컴포넌트 확인 → COMPONENTS 필요 여부
  6. 디버그 모드 → cmake --debug-find로 검색 경로 확인
  7. 패키지 매니저 사용 → vcpkg/Conan으로 자동화

한 줄 요약: Could NOT find은 CMake가 라이브러리 경로를 모를 때 나오므로, CMAKE_PREFIX_PATH·버전·컴포넌트를 점검하고 vcpkg/Conan을 쓰면 대부분 해결됩니다. 다음으로 CMake 입문이나 LNK2019 해결을 읽어보면 좋습니다.

자주 묻는 질문 (FAQ)

Q. find_package가 성공했는데 링크 에러가 나요.

A: find_package는 성공했지만, target_link_libraries를 안 했거나, 컴포넌트를 잘못 지정했을 수 있습니다. Boost::system 대신 Boost::boost만 링크하면 헤더는 보이지만 라이브러리는 링크 안 됩니다.

Q. vcpkg로 설치했는데 find_package가 실패합니다.

A: toolchain 파일을 지정하지 않았을 가능성이 큽니다. 반드시 -DCMAKE_TOOLCHAIN_FILE=.../vcpkg.cmake를 써야 합니다.

Q. Config 파일 경로를 어떻게 찾나요?

A:

# Linux/macOS
find /usr -name "*Config.cmake" 2>/dev/null | grep -i boost

# Windows (PowerShell)
Get-ChildItem -Recurse -Filter "*Config.cmake" C:\

Q. FetchContent vs find_package, 언제 뭘 쓰나요?

A:

  • find_package: 시스템에 이미 설치된 라이브러리 사용 (빠름)
  • FetchContent: 소스에서 자동 다운로드·빌드 (재현성 좋음, 느림)

CI/CD 환경에서는 FetchContent가 유리하고, 로컬 개발에서는 find_package + vcpkg가 빠릅니다.

관련 글

  • CMake 입문: CMake 기본 개념과 외부 라이브러리 연동
  • CMake 치트시트: FetchContent로 라이브러리 가져오기
  • C++ 패키지 매니저 (vcpkg, Conan): 패키지 매니저 비교와 활용법

Could NOT find 에러는 대부분 경로 문제입니다. 라이브러리가 설치되어 있어도 CMake가 어디를 봐야 하는지 모르면 찾지 못합니다. CMAKE_PREFIX_PATH로 경로를 알려 주거나, vcpkg/Conan 같은 패키지 매니저를 쓰면 이런 문제를 대부분 피할 수 있습니다. 특히 vcpkg는 Windows 환경에서 C++ 라이브러리 관리를 획기적으로 쉽게 만들어 줍니다.

검색 시 참고 키워드: CMake Could NOT find, find_package 실패, CMAKE_PREFIX_PATH, vcpkg toolchain, Boost Config.cmake

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

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

  • C++ 패키지 매니저 | vcpkg·Conan으로 “라이브러리 설치 지옥” 탈출하기
  • C++ LNK2019 | “unresolved external symbol” 링커 에러 원인 5가지와 해결법
  • CMake 입문 | 수십 개 파일 컴파일할 때 필요한 빌드 자동화 (CMakeLists.txt 기초)