1.. figure:: https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png 2 :alt: pybind11 logo 3 4**pybind11 — Seamless operability between C++11 and Python** 5 6|Latest Documentation Status| |Stable Documentation Status| |Gitter chat| |CI| |Build status| 7 8.. warning:: 9 10 Combining older versions of pybind11 (< 2.6.0) with the brand-new Python 11 3.9.0 will trigger undefined behavior that typically manifests as crashes 12 during interpreter shutdown (but could also destroy your data. **You have been 13 warned.**) 14 15 We recommend that you wait for Python 3.9.1 slated for release in December, 16 which will include a `fix <https://github.com/python/cpython/pull/22670>`_ 17 that resolves this problem. In the meantime, please update to the latest 18 version of pybind11 (2.6.0 or newer), which includes a temporary workaround 19 specifically when Python 3.9.0 is detected at runtime. 20 21**pybind11** is a lightweight header-only library that exposes C++ types 22in Python and vice versa, mainly to create Python bindings of existing 23C++ code. Its goals and syntax are similar to the excellent 24`Boost.Python <http://www.boost.org/doc/libs/1_58_0/libs/python/doc/>`_ 25library by David Abrahams: to minimize boilerplate code in traditional 26extension modules by inferring type information using compile-time 27introspection. 28 29The main issue with Boost.Python—and the reason for creating such a 30similar project—is Boost. Boost is an enormously large and complex suite 31of utility libraries that works with almost every C++ compiler in 32existence. This compatibility has its cost: arcane template tricks and 33workarounds are necessary to support the oldest and buggiest of compiler 34specimens. Now that C++11-compatible compilers are widely available, 35this heavy machinery has become an excessively large and unnecessary 36dependency. 37 38Think of this library as a tiny self-contained version of Boost.Python 39with everything stripped away that isn’t relevant for binding 40generation. Without comments, the core header files only require ~4K 41lines of code and depend on Python (2.7 or 3.5+, or PyPy) and the C++ 42standard library. This compact implementation was possible thanks to 43some of the new C++11 language features (specifically: tuples, lambda 44functions and variadic templates). Since its creation, this library has 45grown beyond Boost.Python in many ways, leading to dramatically simpler 46binding code in many common situations. 47 48Tutorial and reference documentation is provided at 49`pybind11.readthedocs.io <https://pybind11.readthedocs.io/en/latest>`_. 50A PDF version of the manual is available 51`here <https://pybind11.readthedocs.io/_/downloads/en/latest/pdf/>`_. 52And the source code is always available at 53`github.com/pybind/pybind11 <https://github.com/pybind/pybind11>`_. 54 55 56Core features 57------------- 58 59 60pybind11 can map the following core C++ features to Python: 61 62- Functions accepting and returning custom data structures per value, 63 reference, or pointer 64- Instance methods and static methods 65- Overloaded functions 66- Instance attributes and static attributes 67- Arbitrary exception types 68- Enumerations 69- Callbacks 70- Iterators and ranges 71- Custom operators 72- Single and multiple inheritance 73- STL data structures 74- Smart pointers with reference counting like ``std::shared_ptr`` 75- Internal references with correct reference counting 76- C++ classes with virtual (and pure virtual) methods can be extended 77 in Python 78 79Goodies 80------- 81 82In addition to the core functionality, pybind11 provides some extra 83goodies: 84 85- Python 2.7, 3.5+, and PyPy/PyPy3 7.3 are supported with an 86 implementation-agnostic interface. 87 88- It is possible to bind C++11 lambda functions with captured 89 variables. The lambda capture data is stored inside the resulting 90 Python function object. 91 92- pybind11 uses C++11 move constructors and move assignment operators 93 whenever possible to efficiently transfer custom data types. 94 95- It’s easy to expose the internal storage of custom data types through 96 Pythons’ buffer protocols. This is handy e.g. for fast conversion 97 between C++ matrix classes like Eigen and NumPy without expensive 98 copy operations. 99 100- pybind11 can automatically vectorize functions so that they are 101 transparently applied to all entries of one or more NumPy array 102 arguments. 103 104- Python’s slice-based access and assignment operations can be 105 supported with just a few lines of code. 106 107- Everything is contained in just a few header files; there is no need 108 to link against any additional libraries. 109 110- Binaries are generally smaller by a factor of at least 2 compared to 111 equivalent bindings generated by Boost.Python. A recent pybind11 112 conversion of PyRosetta, an enormous Boost.Python binding project, 113 `reported <http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf>`_ 114 a binary size reduction of **5.4x** and compile time reduction by 115 **5.8x**. 116 117- Function signatures are precomputed at compile time (using 118 ``constexpr``), leading to smaller binaries. 119 120- With little extra effort, C++ types can be pickled and unpickled 121 similar to regular Python objects. 122 123Supported compilers 124------------------- 125 1261. Clang/LLVM 3.3 or newer (for Apple Xcode’s clang, this is 5.0.0 or 127 newer) 1282. GCC 4.8 or newer 1293. Microsoft Visual Studio 2015 Update 3 or newer 1304. Intel C++ compiler 18 or newer 131 (`possible issue <https://github.com/pybind/pybind11/pull/2573>`_ on 20.2) 1325. Cygwin/GCC (tested on 2.5.1) 1336. NVCC (CUDA 11.0 tested) 1347. NVIDIA PGI (20.7 and 20.9 tested) 135 136About 137----- 138 139This project was created by `Wenzel 140Jakob <http://rgl.epfl.ch/people/wjakob>`_. Significant features and/or 141improvements to the code were contributed by Jonas Adler, Lori A. Burns, 142Sylvain Corlay, Eric Cousineau, Ralf Grosse-Kunstleve, Trent Houliston, Axel 143Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov Johan Mabille, Tomasz Miąsko, 144Dean Moldovan, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim 145Schellart, Henry Schreiner, Ivan Smirnov, Boris Staletic, and Patrick Stewart. 146 147We thank Google for a generous financial contribution to the continuous 148integration infrastructure used by this project. 149 150 151Contributing 152~~~~~~~~~~~~ 153 154See the `contributing 155guide <https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md>`_ 156for information on building and contributing to pybind11. 157 158License 159~~~~~~~ 160 161pybind11 is provided under a BSD-style license that can be found in the 162`LICENSE <https://github.com/pybind/pybind11/blob/master/LICENSE>`_ 163file. By using, distributing, or contributing to this project, you agree 164to the terms and conditions of this license. 165 166.. |Latest Documentation Status| image:: https://readthedocs.org/projects/pybind11/badge?version=latest 167 :target: http://pybind11.readthedocs.org/en/latest 168.. |Stable Documentation Status| image:: https://img.shields.io/badge/docs-stable-blue 169 :target: http://pybind11.readthedocs.org/en/stable 170.. |Gitter chat| image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg 171 :target: https://gitter.im/pybind/Lobby 172.. |CI| image:: https://github.com/pybind/pybind11/workflows/CI/badge.svg 173 :target: https://github.com/pybind/pybind11/actions 174.. |Build status| image:: https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true 175 :target: https://ci.appveyor.com/project/wjakob/pybind11 176