In our previous article,Understanding PHP FFI, we showed how you can use PHP to talk directly to C functions. In this article we will explore how you can do the same thing with Python.

---

Python can talk to native code using an FFI, short for Foreign Function Interface. In plain terms, FFI lets Python call C functions in a shared library without writing a CPython extension. You ship a .so on Linux, a .dylib on macOS, or a .dll on Windows, and then drive it from Python code.

This is a fast lane for three reasons:

• Performance: you can offload hot loops and heavy math to compiled C.
• Interop: you can reuse the giant universe of existing C libraries.
• Control: you keep Python for orchestration while C does the hard labor.

There are two popular tools in Python land:

• ctypes: built in, no extra install, great for quick bindings.
• cffi: third party, closer to C syntax, nicer for big libraries and complex structs.

Below is a quick intro that is still nerd friendly, with two runnable examples, and a practical checklist for mapping functions correctly.

Mental model

A shared library exports symbols. Each symbol is a function or global. Python FFI opens the library file, finds the symbol by name, and calls it using a calling convention. To be safe, Python needs to know the argument types, the return type, and sometimes who owns memory. You provide that metadata and Python handles the rest.

Example 1: ctypes with the C standard library

We will call strlen from the C standard library to count bytes. Then we will call cos from the math library. On Linux, cos lives in libm; on macOS it lives in libSystem; on Windows it is in msvcrt.

import ctypes
import ctypes.util

# Locate the C standard library in a cross platform way
libc_name = ctypes.util.find_library("c")
libm_name = ctypes.util.find_library("m")  # may be None on some platforms

libc = ctypes.CDLL(libc_name)  # C calling convention
strlen = libc.strlen
strlen.argtypes = [ctypes.c_char_p]
strlen.restype = ctypes.c_size_t

print(strlen(b"hello ffi"))  # 9

# Math: cos(double) -> double
# Fallback: sometimes cos is in libc already, so try that if libm not found
libm = ctypes.CDLL(libm_name) if libm_name else libc
cos = libm.cos
cos.argtypes = [ctypes.c_double]
cos.restype = ctypes.c_double

print(cos(3.14159))  # roughly -1.0

Notes:

• On Windows, use ctypes.CDLL for cdecl libraries and ctypes.WinDLL for stdcall exports. Most modern Windows system libs use stdcall compatible exports.
• Always set argtypes and restype. Without them, ctypes will guess and you may crash or corrupt the stack.

Example 2: cffi with a tiny custom C API

Now a slightly more structured example using cffi. We will pretend we have a header with a small API.

C header we want to bind:

// file: metrics.h
typedef struct {
    unsigned long count;
    double sum;
} metrics_t;

void metrics_add(metrics_t* m, double value);
double metrics_mean(const metrics_t* m);

In real life you would compile a shared library that implements this header. For this demo we will just declare the types and call into a prebuilt lib you already have, or dlopen None to resolve from the current process for simple functions. The point is to show the ergonomics of cffi.

from cffi import FFI

ffi = FFI()

ffi.cdef(
    "typedef struct { unsigned long count; double sum; } metrics_t;"
    "void metrics_add(metrics_t* m, double value);"
    "double metrics_mean(const metrics_t* m);"
)

# If you have a shared library, pass its path to dlopen.
# For illustration, assume it is ./libmetrics.so or metrics.dll
C = ffi.dlopen("./libmetrics.so")  # adjust for your platform

m = ffi.new("metrics_t *")
for v in [10.0, 20.0, 30.0]:
    C.metrics_add(m, v)

print(int(m.count), float(m.sum))      # 3 and 60.0
print(C.metrics_mean(m))               # 20.0

Why cffi:

• You write C like declarations once in ffi.cdef. No per function boilerplate.
• It handles structs, enums, and pointers with fewer footguns.
• It supports ABI mode, which binds to a compiled library, and API mode, where it can compile a tiny module for you for extra safety and speed.

How do you know what to map

The source of truth is the C header files and the official docs for the library. You need the function names, prototypes, type definitions, constants, and error semantics.

Here is a practical checklist.

1) Find the library

• Linux and BSD: use ldconfig -p, ldd on a program that uses it, or ctypes.util.find_library("name").
• macOS: use ctypes.util.find_library, or inspect /usr/lib and Homebrew paths.
• Windows: you usually know the dll or install path. Add it to PATH or pass an absolute path to CDLL.

2) Confirm exported symbols

• nm -D libxyz.so, objdump -T libxyz.so, or readelf -Ws libxyz.so on ELF.
• otool -L and nm -gU on macOS.
• dumpbin /exports xyz.dll on Windows. If you cannot see the symbol name you expect, search docs for name mangling, underscores, or macro wrappers.

3) Read the headers

• Look for function prototypes, typedefs, struct layouts, and enums.
• Pay attention to const qualifiers and pointer depth like char const * vs char **.
• Watch for macro functions. If a function is a macro, you cannot call it directly via FFI. Often there is a real function behind the macro with a similar name.

4) Map C types to Python FFI types

• integers: c_int, c_uint, c_longlong, etc.
• floating: c_float, c_double.
• strings: char is a pointer to a byte buffer. In ctypes, use c_char_p for simple const char inputs only. For mutable buffers, allocate with create_string_buffer and pass by pointer.
• structs: build ctypes.Structure with fields, or declare in cffi with cdef.
• arrays: pass pointers to the first element, or use cffi new("type[]", n).

5) Calling convention

• On POSIX, the default is cdecl via CDLL.
• On Windows, some legacy APIs use stdcall. Use WinDLL for those exports. If you call a stdcall function with CDLL, the stack will break.

6) Memory ownership

• Does the function return a newly allocated pointer that you must free, or a borrowed pointer you must not free
• For borrows, do not keep references after the owner is gone.
• For owned buffers, call the matching free function from the same library. Consider wrapping the pointer in a Python class that frees in del, or with cffi use ffi.gc(ptr, C.free_like_func).

7) Error reporting

• Many C APIs return negative or zero on error and set errno. In ctypes, set use_errno=True when loading the library or per function, then read ctypes.get_errno().
• On Windows, some functions use GetLastError. ctypes exposes set_last_error and get_last_error.
• Some libraries pass back an error code or write into an out parameter. Always check the docs.

8) Threading and GIL

• Pure FFI calls still hold the Python GIL. For long running calls, consider running them in a thread or process. If you move to a compiled extension you can release the GIL, but that is outside pure FFI.

A tiny mapping table

This cheatsheet covers common C to ctypes mappings.

C type	ctypes type
char	c_char
char *	c_char_p (input only)
void *	c_void_p
int	c_int
unsigned int	c_uint
long	c_long
unsigned long	c_ulong
long long	c_longlong
unsigned long long	c_ulonglong
float	c_float
double	c_double
size_t	c_size_t

For structs, build a subclass of ctypes.Structure with fields. For function pointers, use ctypes.CFUNCTYPE. In cffi, declare the prototype in cdef and use ffi.callback for Python implemented callbacks.

Debugging moves that save hours

• Print the pointer values and sizes. A wrong size is your first hint that a typedef or packing is off.
• Use ctypes.alignment and sizeof to confirm struct layouts.
• If a call returns nonsense, recheck argtypes order and signedness of integers.
• When strings look corrupted, validate encoding and whether the callee expects UTF-8, ASCII, or locale encoding.
• On Linux, use LD_DEBUG=bindings to see loader resolution, or strace to watch file opens.
• If you crash, reduce to the smallest call and stub out optional parameters.

When to choose ctypes vs cffi

• Use ctypes for quick, one file bindings or exploration.
• Use cffi when a library has many structs, macros that map to inline functions, or needs callbacks and opaque handles.
• If you plan to support PyPy, cffi is usually a win since it is used heavily there.

FFI is how you keep Python fun while unlocking native speed. Start with a single function that you care about, write the types explicitly, and build up from there. Once you see a Python script call into a serious C library and return in microseconds, you will not want to go back.

Ready to dive deeper? Check out our advanced section