Install & Compatibility
Where this runs
tested against v2.1.0.20260827 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.006s · 67.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.002s · 19MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FFI
✓ from cffi import FFI
✗ from cffi-stubs import FFI
This quickstart demonstrates a basic usage of `cffi` to call a C standard library function, `puts`. When `types-cffi` is installed, a static type checker will provide type hints for `ffi`, `lib`, and other `cffi` objects, helping to catch type-related errors at development time. The example intentionally avoids platform-specific library loading to be more general, using `ffi.dlopen(None)` for Unix-like systems to access the standard C library.
import os
from cffi import FFI
# Initialize FFI
ffi = FFI()
# Declare C functions (e.g., from the standard C library)
ffi.cdef("""int puts(const char* s);""")
# Load the C library (None on Unix-like systems typically opens libc)
try:
libc = ffi.dlopen(None) # type: ignore
except OSError:
print("Could not load libc. This example might not run on all systems.\n"\
"Ensure a C standard library is available and discoverable.")
exit(1)
# Call a C function with type checking (implicitly using types-cffi)
message = ffi.new("char[]", b"Hello from C via CFFI and types-cffi!")
return_code = libc.puts(message)
print(f"C puts() returned: {return_code}")
# Example of type checking at development time:
# If you misspelled 'puts' or passed an int instead of bytes,
# a type checker (like MyPy) would flag it due to types-cffi.
Debug
Known issues
gotchaInstalling `types-cffi` does not install the `cffi` runtime library. `types-cffi` only provides type annotations. You must install `cffi` separately (e.g., `pip install cffi`) for your code to run.fixEnsure both `pip install types-cffi` and `pip install cffi` are executed.
affects: All versions
breaking`types-cffi` versions are aligned with `cffi` runtime versions. For example, `types-cffi==2.0.x.YYYYMMDD` provides stubs for `cffi==2.0.*`. Using significantly mismatched versions (e.g., `types-cffi` for `cffi` 2.0 with a `cffi` 1.x runtime) can lead to incorrect type checking results or missed errors.fixKeep `types-cffi` and `cffi` versions in sync, ideally pinning both to compatible major/minor versions. Refer to typeshed documentation for specific compatibility.
affects: All versions
deprecatedThe behavior of `ffi.new_handle()` changed in `cffi` v1.3.1 to guarantee unique `void *` values, even when called on the same object multiple times. Code relying on previous CPython behavior (where it might return two `cdata` objects with the same `void *` value) could break if not keeping the result of `ffi.new_handle()` alive explicitly.fixAlways ensure the Python object returned by `ffi.new_handle()` is kept alive for as long as the C `void *` value might be used. Review code for explicit handle management.
affects: <1.3.1 (for reliance on old behavior)
breakingFor `cffi` projects targeting Python 3.12 and newer, if they utilize `cffi` features that historically depended on `distutils` (which was removed in Python 3.12), they must explicitly add `setuptools` as a dependency. `cffi` itself does not add this runtime dependency to avoid unnecessary installs for projects that don't need it.fixAdd `setuptools` to your project's `install_requires` if you build `cffi` extensions that previously relied on `distutils` functionality with Python 3.12 or newer.
affects: cffi <1.16.0 (if targeting Python 3.12+ and using distutils-dependent features)
gotchaWhile typeshed aims to minimize breaking changes in stubs, any update to `types-cffi` (or any `types-*` package) can introduce changes that might cause your code to fail type checking, even if the runtime behavior of `cffi` hasn't changed. This is inherent to the evolving nature of type annotations.fixConsider pinning `types-cffi` to a known good version in your `requirements.txt` (e.g., `types-cffi==2.0.0.20260402`) and update it periodically, or use version ranges that align with `cffi`'s compatibility.
affects: All versions
Upgrade
Version history
2.1.0.20260827latest on PyPI · released Aug 27, 2026
Audit
Dependencies
cffirequiredtypes-cffi provides type hints for the cffi runtime library; cffi itself must be installed separately to execute code.