Python "ImportError: libffi.so.X: cannot open shared object file" in CI

A compiled module (often ctypes-based or cffi-backed) links against the system libffi and the dynamic linker cannot find the expected version. The OS package that provides it is missing or a different soname is installed.

What this error means

Importing a package fails with "ImportError: libffi.so.7: cannot open shared object file: No such file or directory" on a slim runner image.

ImportError: libffi.so.7: cannot open shared object file: No such file or directory

Common causes

The libffi runtime package is not installed

A minimal base image omits libffi, so any extension that links it fails to load.

A soname version mismatch

The image ships libffi.so.8 but the wheel needs libffi.so.7 (or vice versa), so the exact file is absent.

How to fix it

Install the system libffi

Add the OS package that provides the shared library before importing the Python module.

sudo apt-get update
sudo apt-get install -y libffi8

Install a wheel matching the available soname

If the soname differs, pin a wheel built against the libffi the image provides, or install the matching -dev/runtime package.

sudo apt-get install -y libffi-dev

How to prevent it

• Install required runtime lib* packages in a setup step.
• Match wheel builds to the system library versions on the runner.
• Bake needed shared libraries into a custom runner image.

Related guides