Core features

pybind11 can map the following core C++ features to Python:

• Functions accepting and returning custom data structures per value,reference, or pointer

• Instance methods and static methods

• Overloaded functions

• Instance attributes and static attributes

• Arbitrary exception types

• Enumerations

• Callbacks

• Iterators and ranges

• Custom operators

• Single and multiple inheritance

• STL data structures

• Smart pointers with reference counting likestd::shared_ptr

• Internal references with correct reference counting

• C++ classes with virtual (and pure virtual) methods can be extendedin Python

• Integrated NumPy support (NumPy 2 requires pybind11 2.12+)

Goodies

In addition to the core functionality, pybind11 provides some extragoodies:

• CPython 3.8+, PyPy3 7.3.17+, and GraalPy 24.1+ are supported with animplementation-agnostic interface (see older versions for older CPythonand PyPy versions).

• It is possible to bind C++11 lambda functions with capturedvariables. The lambda capture data is stored inside the resultingPython function object.

• pybind11 uses C++11 move constructors and move assignment operatorswhenever possible to efficiently transfer custom data types.

• It’s easy to expose the internal storage of custom data types throughPythons’ buffer protocols. This is handy e.g. for fast conversionbetween C++ matrix classes like Eigen and NumPy without expensivecopy operations.

• pybind11 can automatically vectorize functions so that they aretransparently applied to all entries of one or more NumPy arrayarguments.

• Python’s slice-based access and assignment operations can besupported with just a few lines of code.

• Everything is contained in just a few header files; there is no needto link against any additional libraries.

• Binaries are generally smaller by a factor of at least 2 compared toequivalent bindings generated by Boost.Python. A recent pybind11conversion of PyRosetta, an enormous Boost.Python binding project,reporteda binary size reduction of5.4x and compile time reduction by5.8x.

• Function signatures are precomputed at compile time (usingconstexpr), leading to smaller binaries.

• With little extra effort, C++ types can be pickled and unpickledsimilar to regular Python objects.

Supported compilers

1. Clang/LLVM 3.3 or newer (for Apple Xcode’s clang, this is 5.0.0 ornewer)

2. GCC 4.8 or newer

3. Microsoft Visual Studio 2022 or newer (2019 probably works, but was dropped in CI)

4. Intel classic C++ compiler 18 or newer (ICC 20.2 tested in CI)

5. Cygwin/GCC (previously tested on 2.5.1)

6. NVCC (CUDA 11.0 tested in CI)

7. NVIDIA PGI (20.9 tested in CI)

Supported Platforms

• Windows, Linux, macOS, and iOS

• CPython 3.8+, Pyodide, PyPy, and GraalPy

• C++11, C++14, C++17, C++20, and C++23

About

This project was created byWenzelJakob. Significant features and/orimprovements to the code were contributed byJonas Adler,Lori A. Burns,Sylvain Corlay,Eric Cousineau,Aaron Gokaslan,Ralf Grosse-Kunstleve,Trent Houliston,Axel Huebl,@hulucc,Yannick Jadoul,Sergey Lyskov,Johan Mabille,Tomasz Miąsko,Dean Moldovan,Ben Pritchard,Jason Rhinelander,Boris Schäling,Pim Schellart,Henry Schreiner,Ivan Smirnov,Dustin Spicuzza,Boris Staletic,Ethan Steinberg,Patrick Stewart,Ivor Wanders,andXiaofei Wang.

We thank Google for a generous financial contribution to the continuousintegration infrastructure used by this project.