Python "ImportError: libGL.so.1: cannot open shared object file" in CI

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.

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

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.

sudo apt-get update
sudo apt-get install -y libgl1 libglib2.0-0

Use a headless package variant

For OpenCV, the headless wheel drops the GUI dependency and needs no libGL.

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

How to prevent it

• 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.

Related guides