README.md revision 11986:c12e4625ab56
1 2 3# pybind11 — Seamless operability between C++11 and Python 4 5[](http://pybind11.readthedocs.org/en/master/?badge=master) 6[](http://pybind11.readthedocs.org/en/stable/?badge=stable) 7[](https://travis-ci.org/pybind/pybind11) 8[](https://ci.appveyor.com/project/wjakob/pybind11) 9 10**pybind11** is a lightweight header-only library that exposes C++ types in Python 11and vice versa, mainly to create Python bindings of existing C++ code. Its 12goals and syntax are similar to the excellent 13[Boost.Python](http://www.boost.org/doc/libs/1_58_0/libs/python/doc/) library 14by David Abrahams: to minimize boilerplate code in traditional extension 15modules by inferring type information using compile-time introspection. 16 17The main issue with Boost.Python—and the reason for creating such a similar 18project—is Boost. Boost is an enormously large and complex suite of utility 19libraries that works with almost every C++ compiler in existence. This 20compatibility has its cost: arcane template tricks and workarounds are 21necessary to support the oldest and buggiest of compiler specimens. Now that 22C++11-compatible compilers are widely available, this heavy machinery has 23become an excessively large and unnecessary dependency. 24 25Think of this library as a tiny self-contained version of Boost.Python with 26everything stripped away that isn't relevant for binding generation. Without 27comments, the core header files only require ~2.5K lines of code and depend on 28Python (2.7 or 3.x) and the C++ standard library. This compact implementation 29was possible thanks to some of the new C++11 language features (specifically: 30tuples, lambda functions and variadic templates). Since its creation, this 31library has grown beyond Boost.Python in many ways, leading to dramatically 32simpler binding code in many common situations. 33 34Tutorial and reference documentation is provided at 35[http://pybind11.readthedocs.org/en/master](http://pybind11.readthedocs.org/en/master). 36A PDF version of the manual is available 37[here](https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf). 38 39## Core features 40pybind11 can map the following core C++ features to Python 41 42- Functions accepting and returning custom data structures per value, reference, or pointer 43- Instance methods and static methods 44- Overloaded functions 45- Instance attributes and static attributes 46- Arbitrary exception types 47- Enumerations 48- Callbacks 49- Iterators and ranges 50- Custom operators 51- Single and multiple inheritance 52- STL data structures 53- Iterators and ranges 54- Smart pointers with reference counting like ``std::shared_ptr`` 55- Internal references with correct reference counting 56- C++ classes with virtual (and pure virtual) methods can be extended in Python 57 58## Goodies 59In addition to the core functionality, pybind11 provides some extra goodies: 60 61- pybind11 uses C++11 move constructors and move assignment operators whenever 62 possible to efficiently transfer custom data types. 63 64- It is possible to bind C++11 lambda functions with captured variables. The 65 lambda capture data is stored inside the resulting Python function object. 66 67- It's easy to expose the internal storage of custom data types through 68 Pythons' buffer protocols. This is handy e.g. for fast conversion between 69 C++ matrix classes like Eigen and NumPy without expensive copy operations. 70 71- pybind11 can automatically vectorize functions so that they are transparently 72 applied to all entries of one or more NumPy array arguments. 73 74- Python's slice-based access and assignment operations can be supported with 75 just a few lines of code. 76 77- Everything is contained in just a few header files; there is no need to link 78 against any additional libraries. 79 80- Binaries are generally smaller by a factor of at least 2 compared to 81 equivalent bindings generated by Boost.Python. A recent pybind11 conversion 82 of PyRosetta, an enormous Boost.Python binding project, 83 [reported](http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf) a binary 84 size reduction of **5.4x** and compile time reduction by **5.8x**. 85 86- When supported by the compiler, two new C++14 features (relaxed constexpr and 87 return value deduction) are used to precompute function signatures at compile 88 time, leading to smaller binaries. 89 90- With little extra effort, C++ types can be pickled and unpickled similar to 91 regular Python objects. 92 93## Supported compilers 94 951. Clang/LLVM (any non-ancient version with C++11 support) 962. GCC (any non-ancient version with C++11 support) 973. Microsoft Visual Studio 2015 or newer 984. Intel C++ compiler 16 or newer (15 with a [workaround](https://github.com/pybind/pybind11/issues/276)) 995. Cygwin/GCC (tested on 2.5.1) 100 101## About 102 103This project was created by [Wenzel Jakob](https://www.mitsuba-renderer.org/~wenzel/). 104Significant features and/or improvements to the code were contributed by 105Jonas Adler, 106Sylvain Corlay, 107Trent Houliston, 108Axel Huebl, 109@hulucc, 110Sergey Lyskov 111Johan Mabille, 112Tomasz Miąsko, 113Dean Moldovan, 114Ben Pritchard, 115Jason Rhinelander, 116Boris Schäling, 117Pim Schellart, and 118Ivan Smirnov. 119 120### License 121 122pybind11 is provided under a BSD-style license that can be found in the 123``LICENSE`` file. By using, distributing, or contributing to this project, 124you agree to the terms and conditions of this license. 125
