CMake helpers#

Pybind11 can be used with add_subdirectory(extern/pybind11), or from an install with find_package(pybind11 CONFIG). The interface provided in either case is functionally identical.

pybind11Config.cmake#

Exported variables#

This module sets the following variables in your project:

pybind11_FOUND

true if pybind11 and all required components found on the system

pybind11_VERSION

pybind11 version in format Major.Minor.Release

pybind11_VERSION_TYPE

pybind11 version type (dev* or empty for a release)

pybind11_INCLUDE_DIRS

Directories where pybind11 and python headers are located.

pybind11_INCLUDE_DIR

Directory where pybind11 headers are located.

pybind11_DEFINITIONS

Definitions necessary to use pybind11, namely USING_pybind11.

pybind11_LIBRARIES

Compile flags and python libraries (as needed) to link against.

pybind11_LIBRARY

Empty.

Available components: None

Exported targets#

If pybind11 is found, this module defines the following IMPORTED interface library targets:

pybind11::module

for extension modules.

pybind11::embed

for embedding the Python interpreter.

Python headers, libraries (as needed by platform), and the C++ standard are attached to the target.

Advanced targets are also supplied - these are primary for users building complex applications, and they are available in all modes:

pybind11::headers

Just the pybind11 headers and minimum compile requirements.

pybind11::pybind11

Python headers too.

pybind11::python_link_helper

Just the “linking” part of pybind11:module, for CMake < 3.15.

pybind11::thin_lto

An alternative to INTERPROCEDURAL_OPTIMIZATION.

pybind11::lto

An alternative to INTERPROCEDURAL_OPTIMIZATION (also avoids thin LTO on clang).

pybind11::windows_extras

Adds bigobj and mp for MSVC.

Modes#

There are two modes provided; classic, which is built on the old Python discovery packages in CMake, or the new FindPython mode, which uses FindPython from 3.12+ forward (3.15+ _highly_ recommended). If you set the minimum or maximum version of CMake to 3.27+, then FindPython is the default (since FindPythonInterp/FindPythonLibs has been removed via policy CMP0148).

New FindPython mode#

To activate this mode, either call find_package(Python COMPONENTS Interpreter Development) before finding this package, or set the PYBIND11_FINDPYTHON variable to ON. In this mode, you can either use the basic targets, or use the FindPython tools:

find_package(Python COMPONENTS Interpreter Development)
find_package(pybind11 CONFIG)

# pybind11 method:
pybind11_add_module(MyModule1 src1.cpp)

# Python method:
Python_add_library(MyModule2 src2.cpp)
target_link_libraries(MyModule2 pybind11::headers)
set_target_properties(MyModule2 PROPERTIES
                                INTERPROCEDURAL_OPTIMIZATION ON
                                CXX_VISIBILITY_PRESET ON
                                VISIBILITY_INLINES_HIDDEN ON)

If you build targets yourself, you may be interested in stripping the output for reduced size; this is the one other feature that the helper function gives you.

Classic mode#

Set PythonLibsNew variables to influence python detection and CMAKE_CXX_STANDARD to influence standard setting.

find_package(pybind11 CONFIG REQUIRED)

# Create an extension module
add_library(mylib MODULE main.cpp)
target_link_libraries(mylib PUBLIC pybind11::module)

# Or embed the Python interpreter into an executable
add_executable(myexe main.cpp)
target_link_libraries(myexe PUBLIC pybind11::embed)

Hints#

The following variables can be set to guide the search for this package:

pybind11_DIR

CMake variable, set to directory containing this Config file.

CMAKE_PREFIX_PATH

CMake variable, set to root directory of this package.

PATH

Environment variable, set to bin directory of this package.

CMAKE_DISABLE_FIND_PACKAGE_pybind11

CMake variable, disables find_package(pybind11) when not REQUIRED, perhaps to force internal build.

Commands#

pybind11_add_module#

This module defines the following commands to assist with creating Python modules:

pybind11_add_module(<target>
  [STATIC|SHARED|MODULE]
  [THIN_LTO] [OPT_SIZE] [NO_EXTRAS] [WITHOUT_SOABI]
  <files>...
  )

Add a module and setup all helpers. You can select the type of the library; the default is MODULE. There are several options:

OPT_SIZE

Optimize for size, even if the CMAKE_BUILD_TYPE is not MinSizeRel.

THIN_LTO

Use thin LTO instead of regular if there’s a choice (pybind11’s selection is disabled if CMAKE_INTERPROCEDURAL_OPTIMIZATIONS is set).

WITHOUT_SOABI

Disable the SOABI component (PYBIND11_NEWPYTHON mode only).

NO_EXTRAS

Disable all extras, exit immediately after making the module.

pybind11_strip#

pybind11_strip(<target>)

Strip a target after building it (linux/macOS), called by pybind11_add_module.

pybind11_extension#

pybind11_extension(<target>)

Sets the Python extension name correctly for Python on your platform, called by pybind11_add_module.

pybind11_find_import(module)#

pybind11_find_import(<module> [VERSION <number>] [REQUIRED] [QUIET])

See if a module is installed. Use the registered name (the one on PyPI). You can specify a VERSION, and you can specify REQUIRED or QUIET. Only available if NOPYTHON mode is not active. Sets module_VERSION and module_FOUND. Caches the result once a valid install is found.

Suggested usage#

Using find_package with version info is not recommended except for release versions.

find_package(pybind11 CONFIG)
find_package(pybind11 2.9 EXACT CONFIG REQUIRED)