pybind11

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.

Install

• pip install pybind11 Install core library

Imports

• Generated Python Module

  import your_cpp_module

  Users import the Python module generated by pybind11, not `pybind11` itself at runtime. The `pybind11` Python package provides build-time tools (e.g., include paths).

Quickstart

A minimal example demonstrating how to create a C++ function, expose it to Python using `PYBIND11_MODULE`, and then import and use the generated module from Python. The build command illustrates manual compilation on Unix-like systems, though `setuptools` or `CMake` are typically used for larger projects.

/* 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)