pybind11

A lightweight header-only library that exposes C++ types in Python and vice versa, primarily designed for creating Python bindings of existing C++ code. It provides seamless interoperability between C++11 and Python by enabling developers to map C++ features to Python including functions, classes, instance and static methods, overloaded functions, enumerations, STL data structures, smart pointers, and virtual methods.

Package Information

• Package Name: pybind11
• Language: C++ with Python integration
• Installation: pip install pybind11
• Package Type: Library (header-only C++ with Python build support)

Core Imports

C++ usage (header includes):

#include <pybind11/pybind11.h>

For specific functionality:

#include <pybind11/stl.h>     // STL container support
#include <pybind11/numpy.h>   // NumPy array support
#include <pybind11/embed.h>   // Python embedding

Python usage (build/configuration access):

import pybind11
from pybind11.setup_helpers import Pybind11Extension, build_ext, ParallelCompile

Basic Usage

Creating a Simple Python Module

#include <pybind11/pybind11.h>

int add(int i, int j) {
    return i + j;
}

namespace py = pybind11;

PYBIND11_MODULE(example, m) {
    m.doc() = "pybind11 example plugin";
    m.def("add", &add, "Add two numbers");
}

Building with setup.py

from pybind11.setup_helpers import Pybind11Extension, build_ext
from pybind11 import get_cmake_dir

ext_modules = [
    Pybind11Extension(
        "example",
        ["src/main.cpp"],
        cxx_std=14,
    ),
]

setup(
    name="example",
    ext_modules=ext_modules,
    cmdclass={"build_ext": build_ext},
)

Architecture

pybind11 consists of two main components:

• C++ Header Library: Template-based framework for creating Python bindings, with no runtime dependencies beyond Python and the C++ standard library
• Python Package: Build system integration, path discovery utilities, and installation helpers

The header library uses compile-time introspection to automatically infer type information, eliminating much of the boilerplate code typically required for Python extension modules.

Capabilities

Python Package API

Core Python package functionality for build system integration, path discovery, and extension building utilities.

def get_include(user: bool = False) -> str: ...
def get_cmake_dir() -> str: ...
def get_pkgconfig_dir() -> str: ...

Python Package

Core C++ Binding API

Essential C++ classes and functions for creating Python modules, binding functions, and managing the module lifecycle.

class module_;
template<typename... Options> class class_;
class cpp_function;
PYBIND11_MODULE(name, variable);

Core Binding

Type System and Conversion

Automatic type conversion system between C++ and Python types, including custom type casters and casting policies.

template<typename T> T cast(const handle &obj);
template<typename T> handle cast(T &&value);
enum class return_value_policy;

Type System

STL Integration

Built-in support for automatic conversion of standard C++ containers to Python equivalents, plus utilities for binding container types.

template<typename Vector> void bind_vector(module_ &m, const char *name);
template<typename Map> void bind_map(module_ &m, const char *name);

STL Integration

NumPy Integration

Integration with NumPy arrays for high-performance numerical computing, including buffer protocol support and vectorization.

class array;
template<typename T> class array_t;
template<typename Func> auto vectorize(Func &&f);

NumPy Integration

Exception Handling

Seamless translation between C++ exceptions and Python exceptions, with support for custom exception types.

class error_already_set;
template<typename T> void register_exception();

Exception Handling

Advanced Features

Advanced binding features including inheritance, virtual methods, operators, enumerations, and smart pointer integration.

template<typename T> class enum_;
template<typename... Args> detail::initimpl::constructor<Args...> init();
class trampoline_self_life_support;

Advanced Features

Types

namespace pybind11 {
    // Core object types
    class object;
    class handle;
    class module_;
    
    // Python type wrappers
    class str;
    class bytes;
    class int_;
    class float_;
    class bool_;
    class list;
    class tuple;
    class dict;
    class set;
    class slice;
    
    // Special argument types
    class args;
    class kwargs;
    
    // Version information (Python side)
    extern const char* __version__;
    extern const std::tuple<int, int, int> version_info;
}