0
# pybind11
1
2
A lightweight header-only library that exposes C++ types in Python and vice versa, primarily designed for creating Python bindings of existing C++ code. It provides seamless interoperability between C++11 and Python by enabling developers to map C++ features to Python including functions, classes, instance and static methods, overloaded functions, enumerations, STL data structures, smart pointers, and virtual methods.
3
4
## Package Information
5
6
- **Package Name**: pybind11
7
- **Language**: C++ with Python integration
8
- **Installation**: `pip install pybind11`
9
- **Package Type**: Library (header-only C++ with Python build support)
10
11
## Core Imports
12
13
C++ usage (header includes):
14
15
```cpp
16
#include <pybind11/pybind11.h>
17
```
18
19
For specific functionality:
20
21
```cpp
22
#include <pybind11/stl.h> // STL container support
23
#include <pybind11/numpy.h> // NumPy array support
24
#include <pybind11/embed.h> // Python embedding
25
```
26
27
Python usage (build/configuration access):
28
29
```python
30
import pybind11
31
from pybind11.setup_helpers import Pybind11Extension, build_ext, ParallelCompile
32
```
33
34
## Basic Usage
35
36
### Creating a Simple Python Module
37
38
```cpp
39
#include <pybind11/pybind11.h>
40
41
int add(int i, int j) {
42
return i + j;
43
}
44
45
namespace py = pybind11;
46
47
PYBIND11_MODULE(example, m) {
48
m.doc() = "pybind11 example plugin";
49
m.def("add", &add, "Add two numbers");
50
}
51
```
52
53
### Building with setup.py
54
55
```python
56
from pybind11.setup_helpers import Pybind11Extension, build_ext
57
from pybind11 import get_cmake_dir
58
59
ext_modules = [
60
Pybind11Extension(
61
"example",
62
["src/main.cpp"],
63
cxx_std=14,
64
),
65
]
66
67
setup(
68
name="example",
69
ext_modules=ext_modules,
70
cmdclass={"build_ext": build_ext},
71
)
72
```
73
74
## Architecture
75
76
pybind11 consists of two main components:
77
78
- **C++ Header Library**: Template-based framework for creating Python bindings, with no runtime dependencies beyond Python and the C++ standard library
79
- **Python Package**: Build system integration, path discovery utilities, and installation helpers
80
81
The header library uses compile-time introspection to automatically infer type information, eliminating much of the boilerplate code typically required for Python extension modules.
82
83
## Capabilities
84
85
### Python Package API
86
87
Core Python package functionality for build system integration, path discovery, and extension building utilities.
88
89
```python { .api }
90
def get_include(user: bool = False) -> str: ...
91
def get_cmake_dir() -> str: ...
92
def get_pkgconfig_dir() -> str: ...
93
```
94
95
[Python Package](./python-package.md)
96
97
### Core C++ Binding API
98
99
Essential C++ classes and functions for creating Python modules, binding functions, and managing the module lifecycle.
100
101
```cpp { .api }
102
class module_;
103
template<typename... Options> class class_;
104
class cpp_function;
105
PYBIND11_MODULE(name, variable);
106
```
107
108
[Core Binding](./core-binding.md)
109
110
### Type System and Conversion
111
112
Automatic type conversion system between C++ and Python types, including custom type casters and casting policies.
113
114
```cpp { .api }
115
template<typename T> T cast(const handle &obj);
116
template<typename T> handle cast(T &&value);
117
enum class return_value_policy;
118
```
119
120
[Type System](./type-system.md)
121
122
### STL Integration
123
124
Built-in support for automatic conversion of standard C++ containers to Python equivalents, plus utilities for binding container types.
125
126
```cpp { .api }
127
template<typename Vector> void bind_vector(module_ &m, const char *name);
128
template<typename Map> void bind_map(module_ &m, const char *name);
129
```
130
131
[STL Integration](./stl-integration.md)
132
133
### NumPy Integration
134
135
Integration with NumPy arrays for high-performance numerical computing, including buffer protocol support and vectorization.
136
137
```cpp { .api }
138
class array;
139
template<typename T> class array_t;
140
template<typename Func> auto vectorize(Func &&f);
141
```
142
143
[NumPy Integration](./numpy-integration.md)
144
145
### Exception Handling
146
147
Seamless translation between C++ exceptions and Python exceptions, with support for custom exception types.
148
149
```cpp { .api }
150
class error_already_set;
151
template<typename T> void register_exception();
152
```
153
154
[Exception Handling](./exception-handling.md)
155
156
### Advanced Features
157
158
Advanced binding features including inheritance, virtual methods, operators, enumerations, and smart pointer integration.
159
160
```cpp { .api }
161
template<typename T> class enum_;
162
template<typename... Args> detail::initimpl::constructor<Args...> init();
163
class trampoline_self_life_support;
164
```
165
166
[Advanced Features](./advanced-features.md)
167
168
## Types
169
170
```cpp { .api }
171
namespace pybind11 {
172
// Core object types
173
class object;
174
class handle;
175
class module_;
176
177
// Python type wrappers
178
class str;
179
class bytes;
180
class int_;
181
class float_;
182
class bool_;
183
class list;
184
class tuple;
185
class dict;
186
class set;
187
class slice;
188
189
// Special argument types
190
class args;
191
class kwargs;
192
193
// Version information (Python side)
194
extern const char* __version__;
195
extern const std::tuple<int, int, int> version_info;
196
}
197
```