README.md revision 14299
111986Sandreas.sandberg@arm.com 211986Sandreas.sandberg@arm.com 311986Sandreas.sandberg@arm.com# pybind11 — Seamless operability between C++11 and Python 411986Sandreas.sandberg@arm.com 511986Sandreas.sandberg@arm.com[](http://pybind11.readthedocs.org/en/master/?badge=master) 611986Sandreas.sandberg@arm.com[](http://pybind11.readthedocs.org/en/stable/?badge=stable) 712037Sandreas.sandberg@arm.com[](https://gitter.im/pybind/Lobby) 811986Sandreas.sandberg@arm.com[](https://travis-ci.org/pybind/pybind11) 911986Sandreas.sandberg@arm.com[](https://ci.appveyor.com/project/wjakob/pybind11) 1011986Sandreas.sandberg@arm.com 1111986Sandreas.sandberg@arm.com**pybind11** is a lightweight header-only library that exposes C++ types in Python 1211986Sandreas.sandberg@arm.comand vice versa, mainly to create Python bindings of existing C++ code. Its 1311986Sandreas.sandberg@arm.comgoals and syntax are similar to the excellent 1411986Sandreas.sandberg@arm.com[Boost.Python](http://www.boost.org/doc/libs/1_58_0/libs/python/doc/) library 1511986Sandreas.sandberg@arm.comby David Abrahams: to minimize boilerplate code in traditional extension 1611986Sandreas.sandberg@arm.commodules by inferring type information using compile-time introspection. 1711986Sandreas.sandberg@arm.com 1811986Sandreas.sandberg@arm.comThe main issue with Boost.Python—and the reason for creating such a similar 1911986Sandreas.sandberg@arm.comproject—is Boost. Boost is an enormously large and complex suite of utility 2011986Sandreas.sandberg@arm.comlibraries that works with almost every C++ compiler in existence. This 2111986Sandreas.sandberg@arm.comcompatibility has its cost: arcane template tricks and workarounds are 2211986Sandreas.sandberg@arm.comnecessary to support the oldest and buggiest of compiler specimens. Now that 2311986Sandreas.sandberg@arm.comC++11-compatible compilers are widely available, this heavy machinery has 2411986Sandreas.sandberg@arm.combecome an excessively large and unnecessary dependency. 2511986Sandreas.sandberg@arm.com 2611986Sandreas.sandberg@arm.comThink of this library as a tiny self-contained version of Boost.Python with 2711986Sandreas.sandberg@arm.comeverything stripped away that isn't relevant for binding generation. Without 2812037Sandreas.sandberg@arm.comcomments, the core header files only require ~4K lines of code and depend on 2912037Sandreas.sandberg@arm.comPython (2.7 or 3.x, or PyPy2.7 >= 5.7) and the C++ standard library. This 3012037Sandreas.sandberg@arm.comcompact implementation was possible thanks to some of the new C++11 language 3112037Sandreas.sandberg@arm.comfeatures (specifically: tuples, lambda functions and variadic templates). Since 3212037Sandreas.sandberg@arm.comits creation, this library has grown beyond Boost.Python in many ways, leading 3312037Sandreas.sandberg@arm.comto dramatically simpler binding code in many common situations. 3411986Sandreas.sandberg@arm.com 3511986Sandreas.sandberg@arm.comTutorial and reference documentation is provided at 3611986Sandreas.sandberg@arm.com[http://pybind11.readthedocs.org/en/master](http://pybind11.readthedocs.org/en/master). 3711986Sandreas.sandberg@arm.comA PDF version of the manual is available 3811986Sandreas.sandberg@arm.com[here](https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf). 3911986Sandreas.sandberg@arm.com 4011986Sandreas.sandberg@arm.com## Core features 4111986Sandreas.sandberg@arm.compybind11 can map the following core C++ features to Python 4211986Sandreas.sandberg@arm.com 4311986Sandreas.sandberg@arm.com- Functions accepting and returning custom data structures per value, reference, or pointer 4411986Sandreas.sandberg@arm.com- Instance methods and static methods 4511986Sandreas.sandberg@arm.com- Overloaded functions 4611986Sandreas.sandberg@arm.com- Instance attributes and static attributes 4711986Sandreas.sandberg@arm.com- Arbitrary exception types 4811986Sandreas.sandberg@arm.com- Enumerations 4911986Sandreas.sandberg@arm.com- Callbacks 5011986Sandreas.sandberg@arm.com- Iterators and ranges 5111986Sandreas.sandberg@arm.com- Custom operators 5211986Sandreas.sandberg@arm.com- Single and multiple inheritance 5311986Sandreas.sandberg@arm.com- STL data structures 5411986Sandreas.sandberg@arm.com- Smart pointers with reference counting like ``std::shared_ptr`` 5511986Sandreas.sandberg@arm.com- Internal references with correct reference counting 5611986Sandreas.sandberg@arm.com- C++ classes with virtual (and pure virtual) methods can be extended in Python 5711986Sandreas.sandberg@arm.com 5811986Sandreas.sandberg@arm.com## Goodies 5911986Sandreas.sandberg@arm.comIn addition to the core functionality, pybind11 provides some extra goodies: 6011986Sandreas.sandberg@arm.com 6112037Sandreas.sandberg@arm.com- Python 2.7, 3.x, and PyPy (PyPy2.7 >= 5.7) are supported with an 6212037Sandreas.sandberg@arm.com implementation-agnostic interface. 6311986Sandreas.sandberg@arm.com 6411986Sandreas.sandberg@arm.com- It is possible to bind C++11 lambda functions with captured variables. The 6511986Sandreas.sandberg@arm.com lambda capture data is stored inside the resulting Python function object. 6611986Sandreas.sandberg@arm.com 6712037Sandreas.sandberg@arm.com- pybind11 uses C++11 move constructors and move assignment operators whenever 6812037Sandreas.sandberg@arm.com possible to efficiently transfer custom data types. 6912037Sandreas.sandberg@arm.com 7011986Sandreas.sandberg@arm.com- It's easy to expose the internal storage of custom data types through 7111986Sandreas.sandberg@arm.com Pythons' buffer protocols. This is handy e.g. for fast conversion between 7211986Sandreas.sandberg@arm.com C++ matrix classes like Eigen and NumPy without expensive copy operations. 7311986Sandreas.sandberg@arm.com 7411986Sandreas.sandberg@arm.com- pybind11 can automatically vectorize functions so that they are transparently 7511986Sandreas.sandberg@arm.com applied to all entries of one or more NumPy array arguments. 7611986Sandreas.sandberg@arm.com 7711986Sandreas.sandberg@arm.com- Python's slice-based access and assignment operations can be supported with 7811986Sandreas.sandberg@arm.com just a few lines of code. 7911986Sandreas.sandberg@arm.com 8011986Sandreas.sandberg@arm.com- Everything is contained in just a few header files; there is no need to link 8111986Sandreas.sandberg@arm.com against any additional libraries. 8211986Sandreas.sandberg@arm.com 8311986Sandreas.sandberg@arm.com- Binaries are generally smaller by a factor of at least 2 compared to 8411986Sandreas.sandberg@arm.com equivalent bindings generated by Boost.Python. A recent pybind11 conversion 8511986Sandreas.sandberg@arm.com of PyRosetta, an enormous Boost.Python binding project, 8611986Sandreas.sandberg@arm.com [reported](http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf) a binary 8711986Sandreas.sandberg@arm.com size reduction of **5.4x** and compile time reduction by **5.8x**. 8811986Sandreas.sandberg@arm.com 8914299Sbbruce@ucdavis.edu- Function signatures are precomputed at compile time (using ``constexpr``), 9014299Sbbruce@ucdavis.edu leading to smaller binaries. 9111986Sandreas.sandberg@arm.com 9211986Sandreas.sandberg@arm.com- With little extra effort, C++ types can be pickled and unpickled similar to 9311986Sandreas.sandberg@arm.com regular Python objects. 9411986Sandreas.sandberg@arm.com 9511986Sandreas.sandberg@arm.com## Supported compilers 9611986Sandreas.sandberg@arm.com 9712037Sandreas.sandberg@arm.com1. Clang/LLVM 3.3 or newer (for Apple Xcode's clang, this is 5.0.0 or newer) 9812037Sandreas.sandberg@arm.com2. GCC 4.8 or newer 9912037Sandreas.sandberg@arm.com3. Microsoft Visual Studio 2015 Update 3 or newer 10014299Sbbruce@ucdavis.edu4. Intel C++ compiler 17 or newer (16 with pybind11 v2.0 and 15 with pybind11 v2.0 and a [workaround](https://github.com/pybind/pybind11/issues/276)) 10111986Sandreas.sandberg@arm.com5. Cygwin/GCC (tested on 2.5.1) 10211986Sandreas.sandberg@arm.com 10311986Sandreas.sandberg@arm.com## About 10411986Sandreas.sandberg@arm.com 10512037Sandreas.sandberg@arm.comThis project was created by [Wenzel Jakob](http://rgl.epfl.ch/people/wjakob). 10611986Sandreas.sandberg@arm.comSignificant features and/or improvements to the code were contributed by 10711986Sandreas.sandberg@arm.comJonas Adler, 10814299Sbbruce@ucdavis.eduLori A. Burns, 10911986Sandreas.sandberg@arm.comSylvain Corlay, 11011986Sandreas.sandberg@arm.comTrent Houliston, 11111986Sandreas.sandberg@arm.comAxel Huebl, 11211986Sandreas.sandberg@arm.com@hulucc, 11311986Sandreas.sandberg@arm.comSergey Lyskov 11411986Sandreas.sandberg@arm.comJohan Mabille, 11511986Sandreas.sandberg@arm.comTomasz Miąsko, 11611986Sandreas.sandberg@arm.comDean Moldovan, 11711986Sandreas.sandberg@arm.comBen Pritchard, 11811986Sandreas.sandberg@arm.comJason Rhinelander, 11911986Sandreas.sandberg@arm.comBoris Schäling, 12012037Sandreas.sandberg@arm.comPim Schellart, 12114299Sbbruce@ucdavis.eduHenry Schreiner, 12212037Sandreas.sandberg@arm.comIvan Smirnov, and 12312037Sandreas.sandberg@arm.comPatrick Stewart. 12411986Sandreas.sandberg@arm.com 12511986Sandreas.sandberg@arm.com### License 12611986Sandreas.sandberg@arm.com 12711986Sandreas.sandberg@arm.compybind11 is provided under a BSD-style license that can be found in the 12811986Sandreas.sandberg@arm.com``LICENSE`` file. By using, distributing, or contributing to this project, 12911986Sandreas.sandberg@arm.comyou agree to the terms and conditions of this license. 130
