Calling C or C++ from Python: Building Python Bindings

By the end of this page, you will understand what a Python binding is, the main ways to connect Python with C or C++ code, and when to choose tools such as ctypes, Python C extensions, Cython, or C++ binding libraries like pybind11. You will also see simple examples and learn the trade-offs between speed of setup, ease of maintenance, and control.

A Python binding is a layer that allows Python code to call functions written in another language, such as C or C++.

This matters because many real-world libraries are written in C or C++ for:

• performance
• access to system APIs
• reuse of existing native code
• hardware or OS integration

When Python talks to native code, there are two main problems to solve:

1. How to load or compile the native code
2. How to convert data between Python objects and C/C++ types

Common approaches

1. ctypes

• Built into Python
• Good for calling functions from a compiled C-style shared library (.dll on Windows)
• Fast to start with
• Best when the API is simple and uses plain C types

2. Python C extension API

• Write a module in C or C++ using Python's native extension interface
• Very powerful
• More verbose and lower-level
• Useful when you want full control

3. Cython

• Lets you write Python-like code that wraps C/C++
• Easier than writing raw C extensions for many cases
• Good balance of performance and productivity

4. C++ binding libraries such as pybind11

• Designed specifically for exposing C++ classes and functions to Python
• Much easier than using the raw Python C API directly for C++
• Very common in modern C++ projects

Why C and C++ are different

A C library usually exposes plain functions like this:

Think of Python as a receptionist who speaks Python, and your C or C++ library as an engineer who speaks another language.

A binding is the interpreter between them.

• Python says: "Call add(2, 3)"
• The binding translates that into a native call the library understands
• The library returns a result
• The binding translates it back into a Python value

Different tools are different kinds of interpreters:

• ctypes is like using a phrasebook for simple conversations
• Cython is like hiring a trained bilingual assistant
• pybind11 is like having a specialist for C++ conversations
• the Python C API is like doing the translation manually yourself

Option 1: Call a C library with ctypes

Suppose a DLL exports this C function:

int add(int a, int b);

You can call it from Python like this:

import ctypes

lib = ctypes.CDLL("mylib.dll")

lib.add.argtypes = [ctypes.c_int, ctypes.c_int]
lib.add.restype = ctypes.c_int

result = lib.add(2, 3)
print(result)  # 5

What this does

• CDLL loads the DLL
• argtypes tells Python what argument types the function expects
• restype tells Python what type comes back

This is often the quickest route for a simple C API.

Option 2: Expose C++ with pybind11

C++ code:

#include <pybind11/pybind11.h>

int  {
     a + b;
}

 py = pybind11;

(example, m) {
    m.(, &add, );
}

Consider this Python example using ctypes:

import ctypes

lib = ctypes.CDLL("mylib.dll")
lib.add.argtypes = [ctypes.c_int, ctypes.c_int]
lib.add.restype = ctypes.c_int

answer = lib.add(10, 20)
print(answer)

Step by step

1. Import ctypes

import ctypes

This gives Python tools for working with shared libraries and C-compatible data types.

2. Load the DLL

lib = ctypes.CDLL("mylib.dll")

Python loads the compiled native library into memory.

3. Define the parameter types

lib.add.argtypes = [ctypes.c_int, ctypes.c_int]

This tells Python that add expects two C integers.

4. Define the return type

lib.add.restype = ctypes.c_int

This tells Python to interpret the result as a C integer.

5. Call the native function

Python bindings to C or C++ are widely used in practice.

Common scenarios

Using a high-performance library

A team has a fast image-processing library in C++ and wants Python scripts to use it for automation.

Reusing existing native code

A company already has a mature C library for device communication and wants a Python interface instead of rewriting it.

Accessing operating system or hardware APIs

Some APIs are easier or only practical to access through native libraries.

Scientific and numeric computing

Many scientific Python tools rely on C or C++ under the hood for speed.

Game tools and simulation

A simulation engine may be written in C++, while Python is used for scripting, testing, or configuration.

Practical examples

• wrapping a compression library so Python can compress files faster
• calling a native DLL that talks to industrial hardware
• exposing a C++ geometry engine to Python for data analysis
• using a native parser in a Python command-line tool

In real projects, developers usually do not expose every internal native function directly. They build a small, clean Python-facing API.

Common patterns

Thin wrapper layer

A wrapper translates between Python-friendly values and lower-level native calls.

Example idea:

# Python-facing API
result = image.resize(width=200, height=100)

Behind the scenes, the binding may call several native functions.

Validation before native calls

Developers often validate input in Python before calling C/C++.

def safe_add(lib, a, b):
    if not isinstance(a, int) or not isinstance(b, int):
        raise TypeError("a and b must be integers")
    return lib.add(a, b)

This prevents confusing low-level errors.

Error translation

Native code may use error codes or exceptions. Good bindings convert these into Python exceptions.

• C error code -> RuntimeError or custom exception

1. Using the wrong tool for the job

Trying to wrap a complex C++ class library with ctypes is usually painful.

Better approach

• Use ctypes for simple C APIs
• Use pybind11 or Cython for C++

2. Forgetting to match types exactly

Broken example:

import ctypes

lib = ctypes.CDLL("mylib.dll")
lib.add.argtypes = [ctypes.c_double, ctypes.c_double]  # wrong
lib.add.restype = ctypes.c_int

If the real function expects int, this mismatch can cause incorrect behavior.

3. Ignoring 32-bit vs 64-bit compatibility

A 64-bit Python interpreter cannot load a 32-bit DLL, and vice versa.

Avoid this by checking

• Python architecture
• compiler target
• DLL architecture

4. Forgetting symbol export details on Windows

A function must be exported from the DLL or Python cannot find it.

For C, this may involve export declarations. For C++, name mangling can also make symbol names harder to use directly.

5. Calling C++ directly without handling name mangling

Broken idea:

Common options for Python bindings

Quick decision guide

• Simple C library already compiled as a DLL -> ctypes
• C++ classes or methods -> pybind11
• Python-like wrapper syntax with C/C++ support -> Cython
• Maximum low-level control -> Python C API

ctypes essentials

import ctypes
lib = ctypes.CDLL("mylib.dll")
lib.func.argtypes = [ctypes.c_int, ctypes.c_int]
lib.func.restype = ctypes.c_int
result = lib.func(1, 2)

Common ctypes types

• ctypes.c_int
• ctypes.c_double
• ctypes.c_char_p
• ctypes.c_void_p

C++ warning

• C++ names may be mangled
• classes are not easy to call directly via ctypes
• prefer pybind11 or Cython

Windows reminders

What is a Python binding?

A Python binding is code that lets Python call functions or classes written in another language, usually C or C++.

What is the easiest way to call a C library from Python?

For a simple C library with exported functions, ctypes is often the easiest option.

Can Python call C++ directly with ctypes?

Not comfortably. ctypes works best with C-style exported functions, not complex C++ classes or overloaded methods.

What should I use for C++ bindings in Python?

pybind11 is one of the most common and beginner-friendly choices for modern C++ bindings.

Do I need to recompile the C or C++ library?

Not always. If you already have a suitable shared library with a simple C API, you may be able to use it directly with ctypes. For C++ bindings, you often build a wrapper module.

Why does Windows matter for Python bindings?

Windows uses DLLs, and you must match Python's architecture and ensure the DLL exports the required symbols.

Is Cython only for optimization?

No. It is also a practical tool for wrapping C or C++ code and creating Python extensions.

What if my C++ library is too complex to expose directly?

A common approach is to write a simpler C API wrapper around the C++ code, then bind that API to Python.

• Foreign Function Interface (FFI) — The general idea of calling code written in another language.
• Shared libraries — Python bindings often load .dll, .so, or .dylib files.
• Python C API — The low-level API for writing native Python extensions.
• Cython — A common tool for wrapping C/C++ and improving performance.
• pybind11 — A modern library for exposing C++ code to Python.
• Name mangling — Important when working with C++ symbols and linking.
• Data marshaling — The process of converting data between Python and C/C++ representations.
• Memory management — Essential when native code allocates or frees resources.