{"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":[{"note":"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).","symbol":"Generated Python Module","correct":"import your_cpp_module"}],"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,"last_verified":"2026-05-12T23:17:09.814Z","next_check":"2026-06-30T00:00:00.000Z","problems":[{"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})`.","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).","error":"fatal error: pybind11/pybind11.h: No such file or directory"},{"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.","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.","error":"ImportError: dynamic module does not define init function"},{"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.","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.","error":"error LNK2001: unresolved external symbol PyInit_your_module_name"},{"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.","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.","error":"AttributeError: module 'XXX' has no attribute 'YYY'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.0.4","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","installed_version":"3.0.4","pypi_latest":"3.0.4","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"19.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.5,"import_time_s":null,"mem_mb":null,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"21.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.6,"import_time_s":null,"mem_mb":null,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"12.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"12.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"18.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pybind11","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.8,"import_time_s":null,"mem_mb":null,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pybind11","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}