Python "ImportError: libGL.so.1: cannot open shared object file" in CI
By Daniel Zoghalchali·Latchkey
A compiled Python extension (often OpenCV) loads a shared system library at import time, and the dynamic linker cannot find libGL.so.1 because the package that provides it is not installed on the runner.
What this error means
Importing a package fails with "ImportError: libGL.so.1: cannot open shared object file: No such file or directory" on a slim or headless runner image.
python
ImportError: libGL.so.1: cannot open shared object file: No such file or directory
Diagnose it: is it the build backend or a missing system library?
Python packaging failures in CI split into build-backend configuration problems and missing system headers. The traceback usually points at the backend even when the real cause is an absent -dev package.
Terminal
python -m pip install --upgrade pip build
python -m build --wheel 2>&1 | tail -40
# a compiler error naming a .h file is a system dependency, not a Python one# e.g. "Python.h: No such file" -> python3-dev# "openssl/ssl.h" -> libssl-dev
Common causes
A missing system library on a slim image
The Python wheel installed fine, but it dynamically links against libGL, which a minimal base image omits.
A headless environment without GUI libraries
CI runners have no display stack, so OpenGL/X11 shared libraries that some wheels expect are absent.
How to fix it
Install the system library
Add the OS package that provides libGL.so.1 before importing the Python package.
Install required -dev/runtime system libraries in a setup step.
Prefer headless package variants for CI where no display exists.
Bake the needed shared libraries into a custom runner image.
Frequently asked questions
What causes Python "ImportError: libGL.so.1: cannot open shared object file" in CI?
There are 2 common causes: a missing system library on a slim image and a headless environment without gui libraries. The Python wheel installed fine, but it dynamically links against libGL, which a minimal base image omits.
How do I fix Python "ImportError: libGL.so.1: cannot open shared object file" in CI?
There are 2 fixes depending on which cause you have: install the system library and use a headless package variant. Work through them in order, since the first is the most common.
What does Python "ImportError: libGL.so.1: cannot open shared object file" in CI actually mean?
Importing a package fails with "ImportError: libGL.so.1: cannot open shared object file: No such file or directory" on a slim or headless runner image.
How do I stop Python "ImportError: libGL.so.1: cannot open shared object file" in CI happening again?
Install required -dev/runtime system libraries in a setup step. The prevention section lists 3 changes that keep it from recurring.
