CFFI — C Foreign Function Interface for Python

2.0.0 · active · verified Sat Mar 28

CFFI (C Foreign Function Interface) lets Python code call C libraries by declaring C-like function signatures and types that can often be copy-pasted directly from header files. It supports four modes: ABI/API level each with inline or out-of-line (pre-compiled) preparation. The current stable release is 2.0.0 (released September 2025), requiring Python >=3.9. It is the recommended way to interface with C on PyPy and is used as a foundation by cryptography, bcrypt, and many other major Python packages.

Warnings

breaking In 2.0.0, reading a C '_Bool'/'bool' field whose underlying byte is not exactly 0 or 1 now raises an exception instead of returning the raw integer. Previously undefined-behavior values were silently returned.
Fix: If interfacing with a library that stores non-0/1 values in bool fields, replace 'bool' with 'uint8_t' in your ffi.cdef() declaration.
breaking Python 2.7, 3.6, and 3.7 support was dropped. The minimum supported version is now Python 3.9 (as of 2.0.0 PyPI metadata).
Fix: Upgrade to Python 3.9+. If you must target older Pythons, pin cffi<2.
breaking ffi.string() no longer works on bool[] arrays. It previously returned raw bytes up to the first zero byte, which was rarely meaningful.
Fix: Iterate the bool[] directly or cast to uint8_t[] before calling ffi.string().
gotcha char* in C corresponds to bytes in Python 3, not str. Passing a Python str to any char* argument raises TypeError or produces garbage. Always encode strings explicitly: s.encode('utf-8').
Fix: Use b'...' literals or call str.encode() before passing strings to CFFI char* parameters. Decode return values with ffi.string(ptr).decode().
gotcha ABI mode (ffi.dlopen) is error-prone: wrong type declarations cause silent data corruption or crashes rather than compile-time errors. API mode (ffi.set_source + ffi.compile) is verified by a real C compiler.
Fix: Use out-of-line API mode (ffibuilder.set_source + ffibuilder.compile) for production bindings. Reserve ABI/inline mode for quick experiments only.
gotcha On Python 3.12+ any code path that calls ffi.compile() or uses cffi_modules= in setup.py requires setuptools at runtime because distutils was removed. CFFI does not declare this dependency automatically.
Fix: Add 'setuptools' to your package's build-system requires and/or install_requires when using CFFI's build integration.
gotcha ffi.dlopen(None) does not work on Python 3 on Windows. It raises OSError or returns an unusable handle.
Fix: On Windows, use ffi.dlopen('msvcrt') or specify the full path to the target DLL instead of passing None.

Install

pip install cffi Install cffi

Imports

FFI
```
from cffi import FFI
```
Both forms work, but 'from cffi import FFI' is the canonical pattern used throughout the official docs. Using cffi.FFI() directly after a bare import is verbose but not broken.
FFI (out-of-line)
```
from _my_compiled_module import ffi, lib
```
In out-of-line API mode the compiled extension exports its own 'ffi' (CompiledFFI) and 'lib' objects; do not re-instantiate FFI() at runtime.

Quickstart

Inline ABI mode: declare a C function signature and call it via dlopen. No C compiler needed, but prefer out-of-line API mode for production.

from cffi import FFI

ffi = FFI()

# Declare the C function signature (copy-paste from man page / header)
ffi.cdef("""
    size_t strlen(const char *s);
""")

# ABI mode: open the C standard library
C = ffi.dlopen(None)  # None = current process / libc on POSIX
                      # On Windows use ffi.dlopen('msvcrt') instead

# char* arguments must be bytes, not str
result = C.strlen(b"hello, cffi")
print(result)  # 11

# Allocate a C buffer
buf = ffi.new("char[]", b"world")
print(ffi.string(buf))  # b'world'

view raw JSON →