# cmake-conan pulls Conan 2 packages into CMake configure

> cmake-conan is a CMake dependency provider that runs conan install during configuration, so a C++ project resolves packages without editing its CMakeLists.txt. It works well on mainstream toolchains and has a documented list of gaps.

**conan-io/cmake-conan** — CMake wrapper for conan C and C++ package manager

- Repository: https://github.com/conan-io/cmake-conan
- Stars: 930 · Forks: 265
- Language: Python
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/conan-io-cmake-conan

## Why a CMake dependency provider exists at all

Building a C++ project means resolving third party libraries, and CMake has no built-in way to do that. The usual pattern is to run the package manager first, then configure CMake with the paths the package manager produced, which means two commands and a cache file that has to stay in step with the project. cmake-conan removes the manual step. It is a CMake dependency provider for the Conan C and C++ package manager, delivered as a single CMake file, conan_provider.cmake, sitting at the top level of the repository next to an example project and a tests directory. The integration works through the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable, so a project can adopt it without touching its own CMakeLists.txt at all. The audience is C and C++ teams who have already standardised on Conan and want CMake to drive the dependency step instead of a shell script.

## The provider fires at the first find_package call

The mechanism is CMake's dependency provider interface. When conan_provider.cmake is included at the top level of the project, a provider is registered with CMake, and the first find_package() call in the project triggers a conan install. The dependency list comes from the conanfile.txt or conanfile.py at the project root, so the same declarative file Conan already uses drives the CMake side, and the resolved packages are fed back into CMake as find_package results.

That ordering has a consequence the project lists among its known limitations. Any dependency discovered outside find_package, for example through find_program, find_library, find_path or find_file, may not work correctly if it is requested after the first find_package, and it must follow at least one find_package call. The provider is triggered by find_package, not by the start of configure, so a project that searches for a tool before it looks for any package will not get a conan install at that point.

## Cloning develop2 and configuring the bundled example

The quickstart names its prerequisites: CMake 3.24, Conan 2.0.5 and a CMake based project holding a conanfile.txt or conanfile.py. The first step is to take the develop2 branch, which is where the Conan 2 integration lives:

```bash
git clone https://github.com/conan-io/cmake-conan.git -b develop2
```

The repository ships an example under example/ that depends on fmt, with a CMakeLists.txt, a conanfile.txt and a main.cpp. Configuring it means pointing CMake at the provider file with CMAKE_PROJECT_TOP_LEVEL_INCLUDES and naming a build type:

```bash
cd cmake-conan/example
mkdir build
cmake -B build -S . -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=../conan_provider.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
```

The reader should see a configure step that resolves fmt through Conan and a build that links it, with no conan install typed by hand.

## Adding the provider to a project you already maintain

For an existing project the change is one variable and one cache entry. Put a conanfile.txt or conanfile.py at the project root listing the requirements, then pass the provider path when configuring:

```bash
cd [your-project]
mkdir build
cmake -B build -S . -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=[path-to-cmake-conan]/conan_provider.cmake -DCMAKE_BUILD_TYPE=Release
```

The documentation states that this integration does not require any changes to the CMakeLists.txt scripts. That is the main appeal for an existing codebase: nothing in the build definition has to learn about Conan, and a package reference stays an ordinary find_package call. The catch sits in the cache variable itself. The path to conan_provider.cmake is passed on every configure, so each machine and each CI job needs that path available, and cloning the provider becomes part of setup rather than a one-off action on a laptop.

## Profiles are derived from CMake unless you override them

Conan needs profiles describing the host and the build context. The provider derives the host profile from what CMake detected, that is the os, arch, compiler and build_type settings, and anything CMake cannot detect falls back to the default Conan profile. The build profile is the default profile. For this to work a default profile must already exist, otherwise cmake-conan invokes Conan's autodetection mechanism, which tries to guess the system defaults. Where those defaults are wrong, two cache variables change the behaviour: CONAN_HOST_PROFILE and CONAN_BUILD_PROFILE. The documented values cover several shapes:

```bash
-DCONAN_HOST_PROFILE="default;auto-cmake"
-DCONAN_HOST_PROFILE=clang16
-DCONAN_BUILD_PROFILE="/path/to/profile"
-DCONAN_HOST_PROFILE="default;custom"
```

A semicolon separated list forms a compound profile merged from left to right, with the rightmost entry holding priority, and a build_type named in a host profile is ignored.

## One conan install per build type, and the settings it cannot derive

Build type handling depends on the generator. With a single configuration generator, conan install runs once with build_type set to CMAKE_BUILD_TYPE, and that value must not be left empty. With a multi configuration generator it runs twice, once for Release and once for Debug. The CONAN_INSTALL_BUILD_CONFIGURATIONS variable overrides the list:

```bash
-DCONAN_INSTALL_BUILD_CONFIGURATIONS=Release;Debug
```

That variable works with both generator kinds, although only one build type can be given for single configuration generators. There is a further boundary the project states plainly: deriving Conan settings from CMake is supported only on Windows with MSVC, Linux with gcc and Apple with clang. Any other compiler, architecture or variant needs a Conan profile file, which is where the CONAN_BUILD_PROFILE path option earns its place. The provider is a convenience for mainstream toolchains rather than a general settings resolver.

## Known gaps, and a release history with a four year hole

The limitations section names the sharpest edges. Only the CMakeConfigDeps generator is recommended, because it was designed to solve problems the older CMakeDeps had. Build settings that CMakeToolchain would normally provide, the compiler itself and other global build settings, are not covered: the documentation tells you to invoke Conan separately for those, running conan install first and then cmake --preset. On releases, version 0.19.0 was published on 2026-02-09 and is the first tag compatible with Conan 2, while the two earlier tags, 0.18.1 and 0.18.0, date from 2022. The last push to the develop2 branch was on 2026-08-26. The project warns that the tagged releases are not considered stable and that things can break in future releases, and it recommends the develop2 branch for production even though that branch is not released as 1.0 yet. The licence field on the repository says MIT, so embedding the provider file inside a build carries no copyleft obligation to plan for.

## Conclusion

Adopt cmake-conan when the project already uses Conan, uses find_package for its dependencies, and builds on Windows with MSVC, Linux with gcc or Apple with clang, since those are the toolchains the provider can derive settings from. Do not adopt it if you rely on CMakeToolchain for global build settings, if you need the older CMakeDeps generator, or if your dependency is discovered through find_library before any find_package runs. Verify first that your Conan version is 2.0.5 or later and that a default Conan profile exists, because the provider falls back to autodetection only when that profile is missing.

## FAQ

### What does cmake-conan need before it will work?

The quickstart lists CMake 3.24, Conan 2.0.5 and a CMake based project that contains a conanfile.txt or conanfile.py listing the required dependencies. A default Conan profile must also exist, or the provider falls back to Conan's autodetection.

### Do I have to change my CMakeLists.txt to use cmake-conan?

No. The documentation states that the integration does not require any changes to the CMakeLists.txt scripts. You pass the provider path through the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable when configuring.

### Why does cmake-conan fail to find a library found with find_library?

The provider triggers conan install at the first find_package occurrence, so dependencies with logic outside find_package, including find_program, find_library, find_path and find_file, may not work correctly if they come afterwards. They must follow at least one find_package call.

### Which Conan generator should I use with cmake-conan?

Only CMakeConfigDeps is recommended for cmake-conan. It was designed to solve some of the issues that affected the older CMakeDeps generator.

### What licence is cmake-conan released under?

The licence field on the repository says MIT. The project is distributed with a LICENSE file at the top level of the tree.

## Sources

- [conan-io/cmake-conan on GitHub](https://github.com/conan-io/cmake-conan)
- [Issues](https://github.com/conan-io/cmake-conan/issues)
- [License: MIT](https://github.com/conan-io/cmake-conan/blob/develop2/LICENSE)
- [README](https://github.com/conan-io/cmake-conan/blob/develop2/README.md)
- [Releases](https://github.com/conan-io/cmake-conan/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/conan-io-cmake-conan