Introduction

Pybind11 is a lightweight header-only library that allows you to expose C++ functions and classes to Python. It simplifies the process of creating Python bindings for C++ code and allows seamless interoperability between C++ and Python. In this article, we will discuss how to use Pybind11 to use C++ functions and classes in Python with a runnable example code.

Prerequisites

To follow along with this article, you should have:

  • Basic knowledge of C++ and Python
  • Basic knowledge of Python’s C API

Installation

Pybind11 can be installed via pip by running the following command:

1
pip install pybind11

If you prefer to install Pybind11 manually, you can download it from GitHub and build it using CMake.

Example

Let’s say we have a simple C++ class called Calculator that has two member functions add and subtract:

1
2
3
4
5
6
7
8
9
10
class Calculator {
public:
    Calculator() {}
    int add(int x, int y) {
        return x + y;
    }
    int subtract(int x, int y) {
        return x - y;
    }
};

We would like to create a Python wrapper for this class so that we can use it in Python. Here’s how we can do this using Pybind11:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#include <pybind11/pybind11.h>
#include <pybind11/stl.h>

class Calculator {
public:
    Calculator() {}
    int add(int x, int y) {
        return x + y;
    }
    int subtract(int x, int y) {
        return x - y;
    }
};

PYBIND11_MODULE(calculator, m) {
    pybind11::class_<Calculator>(m, "Calculator")
        .def(pybind11::init<>())
        .def("add", &Calculator::add)
        .def("subtract", &Calculator::subtract);
}

Explanation

Let’s break down this code. We start by including the pybind11 header file. Then, we define our Calculator class as before.

Next, we use the PYBIND11_MODULE macro to create a Python module called calculator. This macro takes two arguments: the name of the module and an instance of pybind11::module class that represents the module. In this case, we define the module as m.

We then use the pybind11::class_ template to define the Calculator class as a Python class. The first argument to pybind11::class_ is the Python name of the class ("Calculator"). The second argument is the C++ class that we want to expose (Calculator). We then define the add and subtract member functions using the .def method.

Finally, we need to build this module into a shared library so that we can load it into Python. We can do this using CMake:

1
2
3
4
5
6
7
cmake_minimum_required(VERSION 3.0)

project(calculator)

find_package(pybind11 REQUIRED)

pybind11_add_module(calculator calculator.cpp)

This will build a shared library called calculator.so (on Linux) or calculator.pyd (on Windows).

We can now load this module into Python and use it like any other Python module:

1
2
3
4
5
import calculator

c = calculator.Calculator()
print(c.add(1, 2))      # Output: 3
print(c.subtract(2, 1)) # Output: 1

Conclusion

In this article, we have learned how to use Pybind11 to create Python bindings for C++ classes and functions. Pybind11 simplifies the process of creating Python bindings and allows seamless interoperability between C++ and Python. By following the example code provided in this article, you should be able to start creating your own Python bindings for your C++ code.