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