{"id":1059,"library":"pybind11","title":"pybind11","description":"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+.","status":"active","version":"3.0.3","language":"python","source_language":"en","source_url":"https://github.com/pybind/pybind11","tags":["C++ bindings","interoperability","extension modules","performance","header-only"],"install":[{"cmd":"pip install pybind11","lang":"bash","label":"Install core library"}],"dependencies":[{"reason":"Required for advanced NumPy array handling (e.g., `py::array_t`, `py::vectorize`).","package":"numpy","optional":true}],"imports":[{"wrong":"import your_cpp_module","symbol":"get_include","correct":"from pybind11 import get_include"},{"symbol":"get_cmake_dir","correct":"from pybind11 import get_cmake_dir"},{"symbol":"commands","correct":"from pybind11 import commands"}],"quickstart":{"code":"/* example.cpp */\n#include <pybind11/pybind11.h>\n\nnamespace py = pybind11;\n\nint add(int i, int j) {\n    return i + j;\n}\n\nPYBIND11_MODULE(example, m) {\n    m.doc() = \"pybind11 example plugin\"; // optional module docstring\n\n    m.def(\"add\", &add, \"A function which adds two numbers\");\n}\n\n# Python (in the same directory or after installation)\nimport example\n\nresult = example.add(1, 2)\nprint(f\"The result is: {result}\") # Expected: The result is: 3\n\n# To build from source (Unix-like systems):\n# Ensure C++ compiler (e.g., g++), Python dev headers, and pybind11 are available.\n# c++ -O3 -Wall -shared -std=c++11 -fPIC \\\n#     $(python3 -m pybind11 --includes) example.cpp \\\n#     -o example$(python3 -m pybind11 --extension-suffix)","lang":"python","description":"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."},"warnings":[{"fix":"Rebuild all pybind11-based extensions with pybind11 v3.0.0 or later to ensure compatibility across modules.","message":"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).","severity":"breaking","affected_versions":"3.0.0+"},{"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+.","message":"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.","severity":"breaking","affected_versions":"3.0.0+"},{"fix":"Switch to using `Python_*` variables in your `CMakeLists.txt` for Python detection instead of `PYTHON_*`. Refer to the pybind11 upgrade guide.","message":"In v3.0.0, CMake support defaults to the modern `FindPython` module. Projects using older `PYTHON_*` variables may find them ignored or deprecated.","severity":"breaking","affected_versions":"3.0.0+"},{"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.","message":"The `py::enum_` API for exposing C++ enumerations is deprecated in favor of `py::native_enum`.","severity":"deprecated","affected_versions":"3.0.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Design your C++ modules to be stateless or carefully manage state per interpreter. Initialization functions (`PYBIND11_MODULE`) will run for each interpreter.","message":"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.","severity":"gotcha","affected_versions":"3.0.0+"},{"fix":"Always use `py::cast<TargetType>(py_object_ptr)` with the explicit template argument for safe conversion.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'+11':16 '24.1':69 '3.0.3':47 '3.8':64 '7.3.17':66 'abi':59 'activ':43 'bind':28,71 'boilerpl':34 'bug':50 'bump':60 'c':15,31,70 'code':32 'compil':37 'compile-tim':36 'cpython':63 'creat':26 'current':45 'exist':30 'extens':73 'fix':51 'frequent':49 'graalpi':68 'header':7,77 'header-on':6,76 'interoper':72 'introduc':58 'introspect':39 'librari':9,41 'lightweight':5 'maintain':44 'major':54 'minim':33 'modul':74 'newer':18 'often':57 'oper':13 'perform':75 'primarili':23 'provid':11 'pybind11':1,2 'pypy3':65 'python':20,27 'regular':53 'releas':55 'seamless':12 'support':62 'time':38 'use':24 'version':46","created_at":"2026-04-01T06:54:38.001745+00:00","updated_at":"2026-04-16T18:20:40.560015+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.1.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://pybind11.readthedocs.io","github":"https://github.com/pybind/pybind11","docs":"https://pybind11.readthedocs.io/","changelog":"https://pybind11.readthedocs.io/en/latest/changelog.html","pypi":"https://pypi.org/project/pybind11/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-08-27","next_check":"2026-07-30","install_tag":"stale"}}