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

Python · updated 2026-11-03

Raised at import cv2 on Linux servers and in slim Docker images. The pip package installed fine; the error comes from a system library (libGL, libgthread, libSM) that the regular opencv-python wheel links to for its GUI functions.

Traceback (most recent call last):
  File "/app/thumbs.py", line 2, in <module>
    import cv2
  File "/usr/local/lib/python3.12/site-packages/cv2/__init__.py", line 181, in <module>
    bootstrap()
  File "/usr/local/lib/python3.12/site-packages/cv2/__init__.py", line 153, in bootstrap
    native_module = importlib.import_module("cv2")
ImportError: libGL.so.1: cannot open shared object file: No such file or directory

Quick fix

On servers and in containers, use opencv-python-headless instead of opencv-python: it has the same API without the GUI dependencies. If you need the full package, install the system libraries in your image (apt-get install -y libgl1 libglib2.0-0).

Check what is installed: pip list | grep -i opencv.
Replace opencv-python with opencv-python-headless in requirements (do not install both).
Rebuild the image or environment so the old package is gone.
If you need GUI features (cv2.imshow), install libgl1 and libglib2.0-0 in the Dockerfile instead.
Watch for other packages pulling opencv-python back in as a dependency.

bash

# requirements.txt: headless build for servers and containers
pip uninstall -y opencv-python
pip install opencv-python-headless

# Or, in a Debian/Ubuntu-based Dockerfile, keep the full package:
#   RUN apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
#       && rm -rf /var/lib/apt/lists/*

Why it happens

The desktop OpenCV wheel on a server

opencv-python includes GUI support and links to libGL; python:*-slim images and most servers do not ship it.

A dependency installs opencv-python

Libraries for OCR, image processing or ML can require opencv-python, so it comes back even after you switch to headless.

Both packages installed

Having opencv-python and opencv-python-headless installed together leaves cv2 pointing at whichever was installed last, sometimes the GUI build.

Other missing system libraries

The same pattern shows up as libgthread-2.0.so.0 or libSM.so.6 errors, all solved by the headless build or the matching apt packages.

Other fixes

Older Debian and Ubuntu images name the package libgl1-mesa-glx; newer ones use libgl1.
Pin the headless package in a constraints file so dependencies cannot swap it back.

Same error, other wording

ImportError: libgthread-2.0.so.0: cannot open shared object file: No such file or directory
ImportError: libSM.so.6: cannot open shared object file: No such file or directory
ImportError: libGL.so.1: cannot open shared object file (cv2)

Let your coding agent catch the next one

Runheed records this error in production with the stack trace, the breadcrumbs before it and the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:

> Find the 'libGL.so.1: cannot open shared object file' errors, show me which OpenCV package is installed in that image and what pulled it in, and switch the deployment to opencv-python-headless or add the system libraries.

Plans from $29/mo See what your agent reads See the setupCancel any time from the billing portal