Using Eigen in CMake Projects

Eigen provides native CMake support which allows the library to be easily used in CMake projects.

Note

Configuring and installing Eigen requires CMake 3.18 (or later). The generated Eigen3Config.cmake imposes no version floor of its own, so a project consuming an already-installed Eigen may use an older CMake; the Using FetchContent route below adds Eigen's own build to your project and so requires 3.18 as well.

Eigen exports a CMake target called Eigen3::Eigen which can be imported using the find_package CMake command and used by calling target_link_libraries as in the following example:

cmake_minimum_required (VERSION 3.5)
project (myproject)
 
find_package (Eigen3 REQUIRED NO_MODULE)
 
add_executable (example example.cpp)
target_link_libraries (example Eigen3::Eigen)

The above code snippet must be placed in a file called CMakeLists.txt alongside example.cpp. After running

$ cmake path-to-example-directory

CMake will produce project files that generate an executable called example. Here, path-to-example-directory is the path to the directory that contains both CMakeLists.txt and example.cpp. Note that if you have multiple instances of Eigen installed, find_package will use the first one encountered. To request a specific version of Eigen, use the <version> option in find_package:

find_package(Eigen3 3.4 REQUIRED NO_MODULE)  # Any version >=3.4 but <4.0.0.

Starting with Eigen 3.4.1, we also support a range spanning major versions:

find_package(Eigen3 3.4...5 REQUIRED NO_MODULE)  # Any version >=3.4.1 but <6.0.0.

Note

Version ranges are find_package syntax introduced in CMake 3.19. Older CMake passes 3.4...5 through as a single version string, which Eigen3ConfigVersion.cmake cannot parse and therefore rejects.

Do not forget to set the CMAKE_PREFIX_PATH variable if Eigen is not installed in a default location or if you want to pick a specific version. For instance:

$ cmake path-to-example-directory -DCMAKE_PREFIX_PATH=$HOME/mypackages

An alternative is to set the Eigen3_DIR cmake's variable to the respective path containing the Eigen3*.cmake files. For instance:

$ cmake path-to-example-directory -DEigen3_DIR=$HOME/mypackages/share/eigen3/cmake/

If the REQUIRED option is omitted when locating Eigen using find_package, one can check whether the package was found as follows:

find_package (Eigen3 NO_MODULE)
 
if (TARGET Eigen3::Eigen)
  # Use the imported target
endif (TARGET Eigen3::Eigen)

Using FetchContent

You can use the FetchContent module to download and include Eigen directly in your project without installing it first. This adds Eigen's own build to your project, so it requires CMake 3.18 rather than the 3.11 that introduced FetchContent.

A basic example:

cmake_minimum_required(VERSION 3.18)
project(myproject)
 
include(FetchContent)
FetchContent_Declare(
  Eigen
  GIT_REPOSITORY https://gitlab.com/libeigen/eigen.git
  GIT_TAG        master
  GIT_SHALLOW    TRUE
)
FetchContent_MakeAvailable(Eigen)
 
add_executable(example example.cpp)
target_link_libraries(example Eigen3::Eigen)

Disabling Eigen build options

When Eigen is added as a sub-project, its documentation, testing, and pkg-config targets may collide with your project's own targets. Disable them before calling FetchContent_MakeAvailable:

set(EIGEN_BUILD_DOC OFF CACHE BOOL "" FORCE)
set(EIGEN_BUILD_TESTING OFF CACHE BOOL "" FORCE)
set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
set(EIGEN_BUILD_PKGCONFIG OFF CACHE BOOL "" FORCE)
 
FetchContent_MakeAvailable(Eigen)

Disabling Eigen's install rules

Eigen's install rules are enabled even when it is built as a sub-project, so that a project embedding Eigen can ship it as part of its own package. If your project does not want Eigen's headers to land in CMAKE_INSTALL_PREFIX (or in a CPack package), set EIGEN_INSTALL to OFF:

set(EIGEN_INSTALL OFF CACHE BOOL "" FORCE)
 
FetchContent_MakeAvailable(Eigen)

Eigen then places no file at all under CMAKE_INSTALL_PREFIX, the generated documentation included.

Note

CMake refuses to generate an install(EXPORT ...) whose targets link a target that no installed export set provides. So if you export your own targets and their public interface links Eigen3::Eigen, you must either leave EIGEN_INSTALL on and install Eigen's CMake package alongside them, or consume Eigen through find_package instead of embedding it.

Using EXCLUDE_FROM_ALL

Projects that depend on Eigen should typically exclude installing Eigen by default to avoid overwriting a previous installation. Passing EXCLUDE_FROM_ALL to add_subdirectory drops Eigen's install rules, and in addition keeps Eigen's targets out of the default build. That form works on every CMake version Eigen supports:

add_subdirectory(path/to/eigen eigen-build EXCLUDE_FROM_ALL)

FetchContent_Declare accepts the same keyword, but only from CMake 3.28 onwards, so a project using it has to say so:

cmake_minimum_required(VERSION 3.28)
 
include(FetchContent)
FetchContent_Declare(
  Eigen
  GIT_REPOSITORY https://gitlab.com/libeigen/eigen.git
  GIT_TAG        master
  GIT_SHALLOW    TRUE
  EXCLUDE_FROM_ALL
)
FetchContent_MakeAvailable(Eigen)

Warning

CMake 3.17 through 3.27 accept EXCLUDE_FROM_ALL in FetchContent_Declare without complaint and ignore it, so Eigen is installed anyway. Below 3.28, use EIGEN_INSTALL or the add_subdirectory form.

Note for CMake 3.30 and later

CMake 3.30 changed the default value of the CMP0168 policy so that FetchContent_Declare uses FetchContent_Populate internally with a different sub-build strategy. If you encounter issues with sub-builds you can either upgrade to a compatible Eigen version or set the policy explicitly:

cmake_policy(SET CMP0168 OLD)