{"id":6786,"library":"pybind11-global","title":"Pybind11 (global install marker)","description":"Pybind11 is a C++ header-only library that provides seamless interoperability between C++ and Python, enabling the creation of Python bindings for C++ code and vice versa. The `pybind11-global` PyPI package, version 3.0.3, typically serves as a marker or a convenient way to ensure the necessary pybind11 C++ headers are discoverable for projects building Python extensions. Pybind11 maintains an active release cadence, with major versions introducing significant features and ABI bumps, followed by patch releases for bug fixes and compatibility updates.","status":"active","version":"3.0.3","language":"en","source_language":"en","source_url":"https://github.com/pybind/pybind11","tags":["c++","bindings","extension","foreign function interface","abi","build-tool"],"install":[{"cmd":"pip install pybind11-global","lang":"bash","label":"Install pybind11-global (includes pybind11)"}],"dependencies":[],"imports":[{"note":"Pybind11 is primarily a C++ library. The `pybind11` package (a dependency of `pybind11-global`) provides Python utilities like `get_include()` for build systems (e.g., setuptools), not for direct runtime Python functionality.","symbol":"get_include","correct":"import pybind11\n# ... then use pybind11.get_include() in your setup.py"}],"quickstart":{"code":"import setuptools\nimport pybind11\nimport os\n\n# This part makes the quickstart runnable by creating a dummy C++ source file.\n# In a real project, this file would exist independently.\ncpp_source_code = \"\"\"\n#include <pybind11/pybind11.h>\n#include <pybind11/stl.h> // Optional: for STL containers\n\nnamespace py = pybind11;\n\nint add(int i, int j) {\n    return i + j;\n}\n\nstd::vector<int> square_list(const std::vector<int>& input) {\n    std::vector<int> result;\n    for (int x : input) {\n        result.push_back(x * x);\n    }\n    return result;\n}\n\nPYBIND11_MODULE(my_module, m) {\n    m.doc() = \"pybind11 example plugin\"; // optional module docstring\n\n    m.def(\"add\", &add, \"A function which adds two numbers\");\n    m.def(\"square_list\", &square_list, \"Squares elements of an integer list\");\n}\n\"\"\"\n\ncpp_file_name = \"my_module.cpp\"\nif not os.path.exists(cpp_file_name):\n    with open(cpp_file_name, \"w\") as f:\n        f.write(cpp_source_code)\n\n# Standard setup.py for a pybind11 extension\nsetuptools.setup(\n    name=\"my_pybind11_package\",\n    version=\"0.0.1\",\n    author=\"Checklist.day\",\n    description=\"A minimal pybind11 example buildable via setup.py\",\n    ext_modules=[\n        setuptools.Extension(\n            \"my_module\", # Name of the Python module\n            [cpp_file_name],\n            include_dirs=[pybind11.get_include()], # Get pybind11 headers\n            language='c++',\n            extra_compile_args=[\"-O3\", \"-Wall\", \"-std=c++17\"],\n        ),\n    ],\n    zip_safe=False,\n    python_requires=\">=3.8\",\n)\n\nprint(f\"To build and install: python {os.path.basename(__file__)} install\")\nprint(\"Then, in Python: import my_module; print(my_module.add(1, 2)); print(my_module.square_list([1,2,3]))\")","lang":"python","description":"This quickstart provides a `setup.py` script that defines a simple Python extension module written in C++ using pybind11. To run it, save the code as `setup.py` in a directory, then open a terminal in that directory and execute `python setup.py install`. This will compile the C++ code and install the `my_module` package into your Python environment. After installation, you can open a Python interpreter and import `my_module` to use its `add` and `square_list` functions."},"warnings":[{"fix":"All existing C++ extensions built with pybind11 2.x must be recompiled when upgrading to pybind11 3.x or later. Ensure all dependencies using pybind11 are also updated and recompiled if they link against pybind11.","message":"Pybind11 3.0.0 introduced a significant ABI (Application Binary Interface) bump. This means that C++ extensions compiled with older versions of pybind11 (e.g., 2.x) are not binary compatible with pybind11 3.x.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Focus on C++ development for defining your bindings. Use `import pybind11` only in your build scripts (`setup.py` or similar) to locate the necessary include directories.","message":"Pybind11 is fundamentally a C++ header-only library for creating Python bindings. Its core functionality is written in C++ and compiled into a shared library (e.g., .so, .pyd). The Python package (e.g., `pybind11-global` or `pybind11`) primarily provides the C++ headers and Python-side build-time utilities (like `pybind11.get_include()`) for tools like `setuptools` or `CMake`, not direct Python runtime imports for binding features.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When writing build scripts, import `pybind11` (not `pybind11_global`) to access functions like `pybind11.get_include()`.","message":"The `pybind11-global` package is often a marker or a dependency wrapper. The actual Python utility functions (e.g., `pybind11.get_include()`) that help with the build process are provided by the `pybind11` package, which is a dependency of `pybind11-global`. While installing `pybind11-global` will bring in `pybind11`, remember that the Python-side helpers are prefixed with `pybind11.`","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project targets Python 3.8 or newer when using pybind11 3.x. If you need to support older Python versions, you must use a pybind11 2.x release (e.g., `pip install pybind11<3`).","message":"Pybind11 3.0.0 dropped official support for older Python versions. Specifically, Python 3.6 and 3.7 are no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your build system (e.g., `CMakeLists.txt` or `setup.py` `extra_compile_args`) specifies a C++ standard of C++11 or higher (e.g., `-std=c++17` for GCC/Clang, `/std:c++17` for MSVC).","message":"Pybind11 requires a C++11 compatible compiler at a minimum. For full feature support and modern C++ best practices, using a compiler that supports C++17 or C++20 is often recommended.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}