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

By Kaveh Alemi·Latchkey

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.

python

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.

Terminal

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.

Terminal

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.

Frequently asked questions

What causes ""libffi.so.X: cannot open shared object file""?

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

How do I fix "libffi.so.X: cannot open shared object file"?