Python "ImportError: libX.so: cannot open shared object file"

By Kaveh Alemi·Latchkey

A compiled Python package loaded fine in pip but its C extension needs a system shared library (.so) at import time - and that library is not installed on the runner.

What this error means

The package installs without error, but importing it crashes with ImportError: <lib>.so.N: cannot open shared object file: No such file or directory. The wheel is fine; the OS-level library it links against is missing.

ImportError: libGL.so.1: cannot open shared object file: No such file or directory
# common when importing opencv-python on a headless/slim image

Common causes

Missing system library on a minimal image

Headless and slim images omit common libraries (libGL, libglib, libsndfile). A wheel that dynamically links them imports fine elsewhere but fails here.

Wrong package variant

Some packages ship a headless variant that avoids the dependency (e.g. opencv-python-headless instead of opencv-python).

How to fix it

Install the missing system library

# Debian/Ubuntu - example for libGL.so.1
apt-get update && apt-get install -y libgl1 libglib2.0-0

Use a headless package variant

When a headless build exists, it drops the GUI library dependency entirely.

pip uninstall -y opencv-python
pip install opencv-python-headless

Find what library is missing

1. Read the exact .so name in the ImportError.
2. Map it to a package (apt-file search libGL.so.1).
3. Install that package in the runner image, not just the job.

How to prevent it

• Bake required system libraries into the runner image.
• Prefer headless package variants in CI where available.
• Document the OS-level dependencies your wheels need.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation