CMake API Reference¶

nanobind’s CMake API simplifies the process of building python extension modules. This is needed because quite a few steps are involved: nanobind must build the module, a library component, link the two together, and add a different set of compilation and linker flags depending on the target platform.

If you prefer another build system, then you have the following options:

Nicholas Junge has created a Bazel interface to nanobind. Please report Bazel-specific issues there.
Will Ayd has created a Meson WrapDB package for nanobind. Please report Meson-specific issues on the Meson WrapDB repository.
You could create a new build system from scratch that takes care of these steps. See this file for inspiration on how to do this on Linux. Note that you will be on your own if you choose to go this route—I unfortunately do not have the time to respond to GitHub tickets related to custom build systems.

The section on building extensions provided an introductory example of how to set up a basic build system via the nanobind_add_module() command, which is the high level build interface. The defaults chosen by this function are somewhat opinionated, however. For this reason, nanobind also provides an alternative low level interface that decomposes it into smaller steps.

A later part of this section explains how a Git submodule dependency can be avoided in exchange for a system-provided package.

Finally, the section ends with an explanation of the CMake convenience interface for stub generation.

High-level interface¶

The high-level interface consists of just one CMake command:

nanobind_add_module¶

Compile a nanobind extension module using the specified target name, optional flags, and source code files. Use it as follows:

nanobind_add_module(
  my_ext                   # Target name
  NB_STATIC STABLE_ABI LTO # Optional flags (see below)
  my_ext.h                 # Source code files below
  my_ext.cpp)

It supports the following optional parameters:

`STABLE_ABI`	Perform a stable ABI build, making it possible to use a compiled extension across Python minor versions. Linked builds compile the nanobind library under the limited API and require Python 3.12 or newer; the flag is ignored on unsupported Python versions. Split mode (`BACKEND_MODULE`) always targets the stable ABI with a Python 3.10 floor, and this flag is then redundant.
`STABLE_ABI_VERSION <version>`	Raise the stable ABI floor of a split mode extension to the given `MAJOR.MINOR` Python version (e.g. `3.13`). The default floor is 3.10, or 3.15 in `abi3t` builds. When `scikit-build-core` is used, the floor tracks `tool.scikit-build.wheel.py-api` and this parameter is usually unnecessary.
`FREE_THREADED`	Compile an Python extension that opts into free-threaded (i.e., GIL-less) Python behavior, which requires a special free-threaded build of Python 3.13 or newer. The flag is ignored on unsupported Python versions. Combined with `BACKEND_MODULE`, it targets the provisional `abi3t` stable ABI variant (PEP 803) and requires free-threaded Python 3.15 or newer.
`NB_STATIC`	Compile the core nanobind library as a static library. This simplifies redistribution but can increase the combined binary storage footprint when a project contains many Python extensions (this is the default).
`NB_SHARED`	The opposite of `NB_STATIC`: compile the core nanobind library as a shared library for use in projects that consist of multiple extensions.
`BACKEND_MODULE <name>`	Compile the extension in split mode: it then contains no nanobind library code at all and resolves the compiled backend at import time from the named backend module (`nanobind_backend` is shipped by the nanobind-backend wheel). Accepts a dotted module name, e.g. a backend module bundled inside your own package. Cannot be combined with `NB_STATIC` or `NB_SHARED`.
`BACKEND_PYPI <name>`	Name of the PyPI package shipping the backend module. When the module is missing at import time, the resulting `ImportError` advises the user to `pip install` this package. Defaults to `nanobind-backend` when `BACKEND_MODULE` is not customized; otherwise no hint is added unless this keyword names a package.
`NB_SUPPRESS_WARNINGS`	Mark the include directories of nanobind and Python as SYSTEM include directories, which suppresses any potential warning messages originating there. This is mainly of relevance if your project artificially raises the warning level via flags like `-pedantic`, `-Wcast-qual`, `-Wsign-conversion`.
`PROTECT_STACK`	Keep the stack protector enabled (for both the extension and nanobind’s core library in the linked modes; a split-mode extension contains no library code, and the backend module has its own `PROTECT_STACK` option).
`LTO`	Perform link time optimization.
`NOMINSIZE`	Don’t perform optimizations to minimize binary size.
`NOSTRIP`	Don’t strip unneded symbols and debug information from the compiled extension when performing release builds.
`NB_DOMAIN <name>`	Restrict the inter-extension type visibility to a named subdomain. See the associated FAQ entry for details.
`MUSL_DYNAMIC_LIBCPP`	When cibuildwheel is used to produce musllinux wheels, don’t statically link against `libstdc++` and `libgcc` (which is an optimization that nanobind does by default in this specific case). If this explanation sounds confusing, then you can ignore it. See the detailed description below for more information on this step.

nanobind_add_module() performs the following steps to produce bindings.

It creates a CMake library via add_library(target_name MODULE ...) and enables the use of C++17 features during compilation.
It creates a CMake target for an internal library component required by nanobind (named nanobind-.. where .. depends on the compilation flags). This is only done once when compiling multiple extensions.

This library component can either be a static or shared library depending on whether the optional NB_STATIC or NB_SHARED parameter was provided to nanobind_add_module(). The default is a static build, which simplifies redistribution (only one shared library must be deployed).

When a project contains many Python extensions, a shared build is preferable to avoid unnecessary binary size overheads that arise from redundant copies of the nanobind-... component.
It links the newly created library against the nanobind-.. target.
It appends the library suffix (e.g., .cpython-313-darwin.so) based on information provided by CMake’s FindPython module.
When requested via the optional STABLE_ABI parameter, the build system will create a stable ABI extension module with a different suffix (e.g., .abi3.so).

Once compiled, a stable ABI extension can be reused across Python minor versions. In contrast, ordinary builds are only compatible across patch versions. In non-split builds, this feature requires Python >= 3.12 and is ignored on older versions. Split mode builds always target the stable ABI, with a Python 3.10 floor that can be raised via STABLE_ABI_VERSION. Note that use of the stable ABI without split mode comes at performance cost, since key parts of nanobind can no longer access the internals of various data structures directly. If in doubt, benchmark your code to see if the cost is acceptable.
In non-debug modes, it compiles with size optimizations (i.e., -Os). This is generally the mode that you will want to use for C++/Python bindings. Switching to -O3 would enable further optimizations like vectorization, loop unrolling, etc., but these all increase compilation time and binary size with no real benefit for bindings.

If your project contains portions that benefit from -O3-level optimizations, then it’s better to run two separate compilation steps. An example is shown below:
```
# Compile project code with current optimization mode configured in CMake
add_library(example_lib STATIC source_1.cpp source_2.cpp)
# Need position independent code (-fPIC) to link into 'example_ext' below
set_target_properties(example_lib PROPERTIES POSITION_INDEPENDENT_CODE ON)

# Compile extension module with size optimization and add 'example_lib'
nanobind_add_module(example_ext common.h source_1.cpp source_2.cpp)
target_link_libraries(example_ext PRIVATE example_lib)
```
Size optimizations can be disabled by specifying the optional NOMINSIZE argument, though doing so is not recommended.
On Linux, GCC normally compiles code with -fstack-protector-strong, which inserts stack canaries to defend against attacks where a buffer overflow writes past a stack buffer into the saved return address.

This defense is especially costly for nanobind-based bindings, where it instruments every function binding wrapper and all ndarray-related code. In the test suite, it increases binary size by ~9-12% while adding 1-2% runtime cost. The threat model is questionable in this context, since the arrays being processed are either controlled by Python or validated by nanobind.

The build system therefore disables the stack protector for both the user extension and libnanobind (-fno-stack-protector on Clang/GCC, /GS- on MSVC). To opt out of this feature, pass PROTECT_STACK to nanobind_add_module(), which reverts to the compiler’s default behavior.
It sets the default symbol visibility to hidden so that only functions and types specifically marked for export generate symbols in the resulting binary. This substantially reduces the size of the generated binary.
In release builds, it strips unreferenced functions and debug information names from the resulting binary. This can substantially reduce the size of the generated binary and can be disabled using the optional NOSTRIP argument.
Link-time optimization (LTO) is not active by default; benefits compared to pybind11 are relatively low, and this can make linking a build bottleneck. That said, the optional LTO argument can be specified to enable LTO in release builds.
nanobind’s CMake build system is often combined with cibuildwheel to automate the generation of wheels for many different platforms. One such platform called musllinux exists to create tiny self-contained binaries that are cheap to install in a container environment (Docker, etc.). An issue of the combination with nanobind is that musllinux doesn’t include the libstdc++ and libgcc libraries which nanobind depends on. cibuildwheel then has to ship those along in each wheel, which actually increases their size rather dramatically (by a factor of >5x for small projects). To avoid this, nanobind prefers to link against these libraries statically when it detects a cibuildwheel build targeting musllinux. Pass the MUSL_DYNAMIC_LIBCPP parameter to avoid this behavior.
If desired (via the optional NB_DOMAIN parameter), nanobind will restrict the visibility of symbols to a named subdomain to avoid conflicts between bindings. See the associated FAQ entry for details.

nanobind_add_backend¶

Build a backend module: a Python module that contains the compiled nanobind backend and serves it to extensions built in split mode. See the section on compiling a custom backend for details.

nanobind_add_backend(_backend)   # ships as, e.g., my_package._backend

Backend modules never target the stable ABI and must be built per Python version. On a free-threaded interpreter, the backend is automatically built free-threaded and serves only free-threaded extensions. They always carry nanobind’s detailed assertion messages, since a user who hits one cannot rebuild the backend in Debug mode. The optional parameters PROTECT_STACK, NOMINSIZE, NOSTRIP, and NB_SUPPRESS_WARNINGS have the same meaning as in nanobind_add_module().

Low-level interface¶

Instead of nanobind_add_module() nanobind also exposes a more fine-grained interface to the underlying operations. The following

nanobind_add_module(my_ext NB_SHARED LTO my_ext.cpp)

is equivalent to

# Build the core parts of nanobind once
nanobind_build_library(nanobind SHARED)

# Compile an extension library
add_library(my_ext MODULE my_ext.cpp)

# .. and link it against the nanobind parts
target_link_libraries(my_ext PRIVATE nanobind)

# .. enable size optimizations
nanobind_opt_size(my_ext)

# .. enable link time optimization
nanobind_lto(my_ext)

# .. set the default symbol visibility to 'hidden'
nanobind_set_visibility(my_ext)

# .. strip unneeded symbols and debug info from the binary (only active in release builds)
nanobind_strip(my_ext)

# .. disable the stack protector
nanobind_disable_stack_protector(my_ext)

# .. set the Python extension suffix
nanobind_extension(my_ext)

# .. set important compilation flags
nanobind_compile_options(my_ext)

# .. set important linker flags
nanobind_link_options(my_ext)

# Statically link against libstdc++/libgcc when targeting musllinux
nanobind_musl_static_libcpp(my_ext)

The various commands are described below:

nanobind_build_library¶

Compile the core nanobind library. The function expects only the target name and uses a slightly unusual parameter passing policy: its behavior changes based on whether or not one the following substrings is detected in the target name:

`-static`	Perform a static library build (without this suffix, a shared build is used)
`-abi3`	Perform a stable ABI build targeting Python v3.12+.
`-ft`	Perform a build that opts into the Python 3.13+ free-threaded behavior.
`-ps`	Keep the stack protector enabled (see the `PROTECT_STACK` flag).

# Normal shared library build
nanobind_build_library(nanobind)

# Static ABI3 build
nanobind_build_library(nanobind-static-abi3)

The command also takes an optional FULL_ASSERTIONS flag. nanobind checks many internal invariants and prints a detailed message when one of them fails. Optimized builds normally replace these messages with a generic one that asks the user to rebuild in Debug mode, which saves a few kilobytes of string data. FULL_ASSERTIONS keeps the detailed messages regardless of the build type. nanobind_add_backend() uses this flag because the users of a backend module have no way to rebuild it.

nanobind_opt_size¶

This function enable size optimizations in Release, MinSizeRel, RelWithDebInfo builds. It expects a single target as argument, as in

nanobind_opt_size(my_target)

nanobind_set_visibility¶

This function sets the default symbol visibility to hidden so that only functions and types specifically marked for export generate symbols in the resulting binary. It expects a single target as argument, as in

nanobind_trim(my_target)

This substantially reduces the size of the generated binary.

nanobind_strip¶

This function strips unused and debug symbols in Release and MinSizeRel builds on Linux and macOS. It expects a single target as argument, as in

nanobind_strip(my_target)

nanobind_disable_stack_protector¶

Disables the stack-smashing protector for the specified target in optimized builds. The canary guards against stack buffer overflows, but nanobind’s hot path has only fixed-size stack arrays indexed by the validated argument count, so it is pure overhead there (+8% binary size on Linux). Use it as follows:

nanobind_disable_stack_protector(my_target)

nanobind_extension¶

This function assigns an extension name to the compiled binding, e.g., .cpython-311-darwin.so. Use it as follows:

nanobind_extension(my_target)

nanobind_extension_abi3¶

This function assigns a stable ABI extension name to the compiled binding, e.g., .abi3.so. Use it as follows:

nanobind_extension_abi3(my_target)

nanobind_extension_abi3t¶

This function assigns the abi3t stable ABI extension name of free-threaded Python 3.15+ (PEP 803) to the compiled binding, e.g., .abi3t.so. Use it as follows:

nanobind_extension_abi3t(my_target)

nanobind_compile_options¶

This function sets recommended compilation flags. Currently, it specifies /bigobj and /MP on MSVC builds, and it does nothing other platforms or compilers. Use it as follows:

nanobind_compile_options(my_target)

nanobind_link_options¶

This function sets recommended linker flags. Currently, it controls link time handling of undefined symbols on Apple platforms related to Python C API calls, and it does nothing other platforms. Use it as follows:

nanobind_link_options(my_target)

nanobind_musl_static_libcpp¶

This function passes the linker flags -static-libstdc++ and -static-libgcc to gcc when the environment variable AUDITWHEEL_PLAT contains the string musllinux, which indicates a cibuildwheel build targeting that platform.

The function expects a single target as argument, as in

nanobind_musl_static_libcpp(my_target)

Submodule dependencies¶

nanobind includes a dependency (a fast hash map named tsl::robin_map) as a Git submodule. If you prefer to use another (e.g., system-provided) version of this dependency, set the NB_USE_SUBMODULE_DEPS variable before importing nanobind into CMake. In this case, nanobind’s CMake scripts will internally invoke find_dependency(tsl-robin-map) to locate the associated header files.

Stub generation¶

Nanobind’s CMake tooling includes a convenience command to interface with the stubgen program explained in the section on stub generation.

nanobind_add_stub¶

Import the specified module (MODULE parameter), generate a stub, and write it to the specified file (OUTPUT parameter). Here is an example use:

nanobind_add_stub(
    my_ext_stub
    MODULE my_ext
    OUTPUT my_ext.pyi
    PYTHON_PATH $<TARGET_FILE_DIR:my_ext>
    DEPENDS my_ext
)

The target name (my_ext_stub in this example) must be unique but has no other significance.

stubgen will add all paths specified as part of the PYTHON_PATH block and then execute import my_ext in a Python session. If the extension is not importable, this will cause stub generation to fail.

This command supports the following parameters:

`INSTALL_TIME`	By default, stub generation takes place at build time following generation of all dependencies (see `DEPENDS`). When this parameter is specified, stub generation is instead postponed to the installation phase.
`RECURSIVE`	If specified, the stub generator automatically traverses the module hierarchy and generates a stub for each discovered submodule. The files are either placed right next to the original Python code, or relative to `OUTPUT_PATH`. In this special mode, you may pass multiple arguments `OUTPUT` so that CMake’s dependency management can keep track of the generated files.
`MODULE`	Specifies the name of the module that should be imported. Only a single module can be specified. Mandatory.
`OUTPUT`	Specifies the name of the stub (`.pyi`) file to be written. The path is relative to `CMAKE_CURRENT_BINARY_DIR` for build-time stub generation and relative to `CMAKE_INSTALL_PREFIX` for install-time stub generation. When `RECURSIVE` is set, multiple paths may be specified. Note that these are not actually passed to the stub generator and purely used for dependency management within CMake (e.g., to remove files when executing the `clean` target, or to track dependencies when stub files are subsequently consumed by other targets). This parameter is generally mandatory. When `INSTALL_TIME` is set, it can be omitted since dependency tracking is not needed in this case.
`OUTPUT_PATH`	Overrides the base directory in which stub files should be written. This parameter can only be used when `INSTALL_TIME` or `RECURSIVE` (or both) are set. The path is relative to `CMAKE_CURRENT_BINARY_DIR` for build-time stub generation and relative to `CMAKE_INSTALL_PREFIX` for install-time stub generation.
`PYTHON_PATH`	List of search paths that should be considered when importing the module. The paths are relative to `CMAKE_CURRENT_BINARY_DIR` for build-time stub generation and relative to `CMAKE_INSTALL_PREFIX` for install-time stub generation. The current directory (`"."`) is always included and does not need to be specified. The parameter may contain CMake generator expressions when `nanobind_add_stub()` is used for build-time stub generation. Otherwise, generator expressions should not be used. Optional.
`DEPENDS`	Any targets listed here will be marked as a dependencies. This should generally be used to list the target names of one or more prior `nanobind_add_module()` declarations. Note that this parameter tracks build-time dependencies and does not need to be specified when stub generation occurs at install time (see `INSTALL_TIME`). Optional.
`VERBOSE`	Show status messages generated by `stubgen`.
`EXCLUDE_DOCSTRINGS`	Generate a stub containing only typed signatures without docstrings.
`EXCLUDE_VALUES`	Don’t include the values of variables in the generated stub, only their types.
`INCLUDE_PRIVATE`	Also include private members, whose names begin or end with a single underscore.
`MARKER_FILE`	Typed extensions normally identify themselves via the presence of an empty file named `py.typed` in each module directory. When this parameter is specified, `nanobind_add_stub()` will automatically generate such an empty file as well. Multiple marker file paths can be optionally passed to this parameter.
`PATTERN_FILE`	Specify one or more pattern files used to replace declarations in the stub. The syntax is described in the section on stub generation. When several files are given, their rules are merged in the order specified, and the first matching rule wins.
`COMPONENT`	Specify a component when `INSTALL_TIME` stub generation is used. This is analogous to `install(..., COMPONENT [name])` in other install targets.
`EXCLUDE_FROM_ALL`	If specified, the file is only installed as part of a component-specific installation when `INSTALL_TIME` stub generation is used. This is analogous to `install(..., EXCLUDE_FROM_ALL)` in other install targets.