pybind11
raw JSON → 3.0.3 verified Tue May 12 auth: no python install: stale
pybind11 is a lightweight, header-only library that provides seamless operability between C++11 (and newer) and Python. It's primarily used to create Python bindings for existing C++ code, minimizing boilerplate through compile-time introspection. The library is actively maintained (current version 3.0.3) with frequent bug fixes and regular major releases that often introduce ABI bumps. It supports CPython 3.8+, PyPy3 7.3.17+, and GraalPy 24.1+.
pip install pybind11 Common errors
error fatal error: pybind11/pybind11.h: No such file or directory ↓
cause The C++ compiler cannot find the pybind11 header files, meaning the include path is not correctly set up in the build system (e.g., CMake or Makefile).
fix
Ensure that the
pybind11 include directory is added to your compiler's include paths. With CMake, use find_package(pybind11 REQUIRED) and then target_link_libraries(your_target PRIVATE pybind11::embed) or target_include_directories(your_target PRIVATE ${pybind11_INCLUDE_DIR}). error ImportError: dynamic module does not define init function ↓
cause This error typically occurs when the compiled Python extension module's name (the filename, e.g., `mymodule.so` or `mymodule.pyd`) does not match the name specified in the `PYBIND11_MODULE` macro, or when the module was compiled with a different Python version than the one attempting to import it.
fix
Verify that the filename of your compiled module (e.g.,
example.cpython-3x-y.so) exactly matches the name argument in PYBIND11_MODULE(name, m) in your C++ source, and ensure that your build system links against the correct Python version's libraries. error error LNK2001: unresolved external symbol PyInit_your_module_name ↓
cause This is a Windows-specific linker error (similar to 'undefined symbol' on Unix-like systems) indicating that the entry point function for the Python module (`PyInit_your_module_name`) or other Python C API symbols cannot be found, often due to incorrect linking with the Python library or a mismatch between the module name and the `PYBIND11_MODULE` definition.
fix
Ensure your project is correctly linking against the Python library (e.g.,
python3x.lib on Windows, or -lpython3.x on Linux) and that the module name in PYBIND11_MODULE(your_module_name, m) precisely matches the name used in your Python setup.py or CMakeLists.txt for the target. error AttributeError: module 'XXX' has no attribute 'YYY' ↓
cause This runtime error means that a Python script is trying to access a function, class, or attribute ('YYY') within a pybind11-bound module ('XXX') that was either not exposed (bound) in the C++ code or has a different name than expected.
fix
Double-check your
PYBIND11_MODULE definition in the C++ code to ensure that m.def("YYY", ...) or py::class_<...>(m, "XXX").def("YYY", ...) properly exposes the intended function or method with the correct name. Warnings
breaking pybind11 v3.0.0 introduced an ABI bump. Extensions built with v3.0.0 or later are not ABI-compatible with those built using v2.x versions (e.g., v2.13). ↓
fix Rebuild all pybind11-based extensions with pybind11 v3.0.0 or later to ensure compatibility across modules.
breaking Support for older Python and CMake versions was removed in v3.0.0. Specifically, Python 3.7, PyPy 3.8/3.9, and CMake < 3.15 are no longer supported. ↓
fix Ensure your build environment uses Python 3.8+ (or supported PyPy/GraalPy versions) and CMake 3.15+ when upgrading to pybind11 v3.0.0+.
breaking In v3.0.0, CMake support defaults to the modern `FindPython` module. Projects using older `PYTHON_*` variables may find them ignored or deprecated. ↓
fix Switch to using `Python_*` variables in your `CMakeLists.txt` for Python detection instead of `PYTHON_*`. Refer to the pybind11 upgrade guide.
deprecated The `py::enum_` API for exposing C++ enumerations is deprecated in favor of `py::native_enum`. ↓
fix Migrate to `py::native_enum` for improved integration with Python's `enum` system. While `py::enum_` is still present, it may be removed in a future 3.x release.
gotcha Improper Global Interpreter Lock (GIL) management is a common source of bugs. Avoid invoking Python functions in global static contexts or having global pybind11 objects. ↓
fix Consult the pybind11 documentation on GIL management, use `py::gil_scoped_acquire` or `py::gil_scoped_release` as needed, and consider lazy initialization for global pybind11 objects.
gotcha When working with sub-interpreters (enabled by default in v3.0.0), avoid sharing Python objects across different sub-interpreters and minimize global/static C++ state in your modules. ↓
fix Design your C++ modules to be stateless or carefully manage state per interpreter. Initialization functions (`PYBIND11_MODULE`) will run for each interpreter.
gotcha When casting from a raw `PyObject*` to a `py::object` subclass (e.g., `py::str`), omitting the template argument to `py::cast` will silently result in incorrect behavior. ↓
fix Always use `py::cast<TargetType>(py_object_ptr)` with the explicit template argument for safe conversion.
gotcha The test script being executed is C++ code, not Python code, leading to a `SyntaxError: invalid syntax`. This indicates a fundamental misconfiguration in the test environment rather than a `pybind11`-specific issue. ↓
fix Ensure that the Python interpreter is running a valid Python script. If C++ code needs to be tested, it must be properly compiled, linked, and then imported/called from a Python script.
Install compatibility stale last tested: 2026-05-12 v3.0.4 (up to date)
python os / libc status wheel install import disk mem side effects
3.10 alpine (musl) wheel - - 19.1M - broken
3.10 alpine (musl) - - - - - -
3.10 slim (glibc) wheel 1.5s - 20M - broken
3.10 slim (glibc) - - - - - -
3.11 alpine (musl) wheel - - 21.0M - broken
3.11 alpine (musl) - - - - - -
3.11 slim (glibc) wheel 1.6s - 21M - broken
3.11 slim (glibc) - - - - - -
3.12 alpine (musl) wheel - - 12.8M - broken
3.12 alpine (musl) - - - - - -
3.12 slim (glibc) wheel 1.4s - 13M - broken
3.12 slim (glibc) - - - - - -
3.13 alpine (musl) wheel - - 12.6M - broken
3.13 alpine (musl) - - - - - -
3.13 slim (glibc) wheel 1.4s - 13M - broken
3.13 slim (glibc) - - - - - -
3.9 alpine (musl) wheel - - 18.6M - broken
3.9 alpine (musl) - - - - - -
3.9 slim (glibc) wheel 1.8s - 19M - broken
3.9 slim (glibc) - - - - - -
Imports
- Generated Python Module
import your_cpp_module
Quickstart last tested: 2026-04-24
/* example.cpp */
#include <pybind11/pybind11.h>
namespace py = pybind11;
int add(int i, int j) {
return i + j;
}
PYBIND11_MODULE(example, m) {
m.doc() = "pybind11 example plugin"; // optional module docstring
m.def("add", &add, "A function which adds two numbers");
}
# Python (in the same directory or after installation)
import example
result = example.add(1, 2)
print(f"The result is: {result}") # Expected: The result is: 3
# To build from source (Unix-like systems):
# Ensure C++ compiler (e.g., g++), Python dev headers, and pybind11 are available.
# c++ -O3 -Wall -shared -std=c++11 -fPIC \
# $(python3 -m pybind11 --includes) example.cpp \
# -o example$(python3 -m pybind11 --extension-suffix)