First steps

This sections demonstrates the basic features of pybind11. Before getting started, make sure that development environment is set up to compile the included set of examples, which also double as test cases.

Compiling the test cases

Linux/MacOS

On Linux you’ll need to install the python-dev or python3-dev packages as well as cmake. On Mac OS, the included python version works out of the box, but cmake must still be installed.

After installing the prerequisites, run

cmake .
make -j 4

followed by

make test

Windows

On Windows, use the CMake GUI to create a Visual Studio project. Note that only the 2015 release and newer versions are supported since pybind11 relies on various C++11 language features that break older versions of Visual Studio. After running CMake, open the created pybind11.sln file and perform a release build, which will will produce a file named Release\example.pyd. Copy this file to the example directory and run example\run_test.py using the targeted Python version.

Note

When all tests fail, make sure that

1. The Python binary and the testcases are compiled for the same processor type and bitness (i.e. either i386 or x86_64)
2. The Python binary used to run example\run_test.py matches the Python version specified in the CMake GUI. This is controlled via the PYTHON_EXECUTABLE PYTHON_INCLUDE_DIR, and PYTHON_LIBRARY variables.

See also

Advanced users who are already familiar with Boost.Python may want to skip the tutorial and look at the test cases in the example directory, which exercise all features of pybind11.

Creating bindings for a simple function

Let’s start by creating Python bindings for an extremely simple function, which adds two numbers and returns their result:

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

For simplicity [1], we’ll put both this function and the binding code into a file named example.cpp with the following contents:

#include <pybind11/pybind11.h>

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

namespace py = pybind11;

PYBIND11_PLUGIN(example) {
    py::module m("example", "pybind11 example plugin");

    m.def("add", &add, "A function which adds two numbers");

    return m.ptr();
}

The PYBIND11_PLUGIN() macro creates a function that will be called when an import statement is issued from within Python. The next line creates a module named example (with the supplied docstring). The method module::def() generates binding code that exposes the add() function to Python. The last line returns the internal Python object associated with m to the Python interpreter.

Note

Notice how little code was needed to expose our function to Python: all details regarding the function’s parameters and return value were automatically inferred using template metaprogramming. This overall approach and the used syntax are borrowed from Boost.Python, though the underlying implementation is very different.

pybind11 is a header-only-library, hence it is not necessary to link against any special libraries (other than Python itself). On Windows, use the CMake build file discussed in section Building with CMake. On Linux and Mac OS, the above example can be compiled using the following command

$ c++ -O3 -shared -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --ldflags` example.cpp -o example.so

In general, it is advisable to include several additional build parameters that can considerably reduce the size of the created binary. Refer to section Building with CMake for a detailed example of a suitable cross-platform CMake-based build system.

Assuming that the created file example.so (example.pyd on Windows) is located in the current directory, the following interactive Python session shows how to load and execute the example.

$ python
Python 2.7.10 (default, Aug 22 2015, 20:33:39)
[GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import example
>>> example.add(1, 2)
3L
>>>

Keyword arguments

With a simple modification code, it is possible to inform Python about the names of the arguments (“i” and “j” in this case).

m.def("add", &add, "A function which adds two numbers",
      py::arg("i"), py::arg("j"));

arg is one of several special tag classes which can be used to pass metadata into module::def(). With this modified binding code, we can now call the function using keyword arguments, which is a more readable alternative particularly for functions taking many parameters:

>>> import example
>>> example.add(i=1, j=2)
3L

The keyword names also appear in the function signatures within the documentation.

>>> help(example)

....

FUNCTIONS
    add(...)
        Signature : (i: int, j: int) -> int

        A function which adds two numbers

A shorter notation for named arguments is also available:

// regular notation
m.def("add1", &add, py::arg("i"), py::arg("j"));
// shorthand
using namespace pybind11::literals;
m.def("add2", &add, "i"_a, "j"_a);

The _a suffix forms a C++11 literal which is equivalent to arg. Note that the literal operator must first be made visible with the directive using namespace pybind11::literals. This does not bring in anything else from the pybind11 namespace except for literals.

Default arguments

Suppose now that the function to be bound has default arguments, e.g.:

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

Unfortunately, pybind11 cannot automatically extract these parameters, since they are not part of the function’s type information. However, they are simple to specify using an extension of arg:

m.def("add", &add, "A function which adds two numbers",
      py::arg("i") = 1, py::arg("j") = 2);

The default values also appear within the documentation.

>>> help(example)

....

FUNCTIONS
    add(...)
        Signature : (i: int = 1, j: int = 2) -> int

        A function which adds two numbers

The shorthand notation is also available for default arguments:

// regular notation
m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2);
// shorthand
m.def("add2", &add, "i"_a=1, "j"_a=2);

Supported data types

The following basic data types are supported out of the box (some may require an additional extension header to be included). To pass other data structures as arguments and return values, refer to the section on binding Object-oriented code.

Data type	Description	Header file
int8_t, uint8_t	8-bit integers	pybind11/pybind11.h
int16_t, uint16_t	16-bit integers	pybind11/pybind11.h
int32_t, uint32_t	32-bit integers	pybind11/pybind11.h
int64_t, uint64_t	64-bit integers	pybind11/pybind11.h
ssize_t, size_t	Platform-dependent size	pybind11/pybind11.h
float, double	Floating point types	pybind11/pybind11.h
bool	Two-state Boolean type	pybind11/pybind11.h
char	Character literal	pybind11/pybind11.h
wchar_t	Wide character literal	pybind11/pybind11.h
const char *	UTF-8 string literal	pybind11/pybind11.h
const wchar_t *	Wide string literal	pybind11/pybind11.h
std::string	STL dynamic UTF-8 string	pybind11/pybind11.h
std::wstring	STL dynamic wide string	pybind11/pybind11.h
std::pair<T1, T2>	Pair of two custom types	pybind11/pybind11.h
std::tuple<...>	Arbitrary tuple of types	pybind11/pybind11.h
std::reference_wrapper<...>	Reference type wrapper	pybind11/pybind11.h
std::complex<T>	Complex numbers	pybind11/complex.h
std::array<T, Size>	STL static array	pybind11/stl.h
std::vector<T>	STL dynamic array	pybind11/stl.h
std::list<T>	STL linked list	pybind11/stl.h
std::map<T1, T2>	STL ordered map	pybind11/stl.h
std::unordered_map<T1, T2>	STL unordered map	pybind11/stl.h
std::set<T>	STL ordered set	pybind11/stl.h
std::unordered_set<T>	STL unordered set	pybind11/stl.h
std::function<...>	STL polymorphic function	pybind11/functional.h
Eigen::Matrix<...>	Dense Eigen matrices	pybind11/eigen.h
Eigen::SparseMatrix<...>	Sparse Eigen matrices	pybind11/eigen.h

[1]	In practice, implementation and binding code will generally be located in separate files.