Python 'ImportError: libGL.so.1: cannot open shared object file: No such file or directory' (or libgthread / libSM missing) when importing cv2 in Docker or on a server. How do I fix OpenCV imports?

Cause: the default opencv-python wheel includes GUI support (windows for cv2.imshow) and links against desktop graphics and X11 libraries such as libGL. Slim Docker images, CI runners and headless servers don't have those libraries, so import cv2 fails with a missing .so error before your code runs. Fix (best first): 1. Use the headless build on servers and in containers: pip uninstall -y opencv-python and pip install opencv-python-headless (or opencv-contrib-python-headless if you need the contrib modules). The opencv-python project recommends the headless packages for servers and Docker; they skip GUI components and the X11 dependency chain, and give smaller images. 2. Install only one OpenCV package in an environment: the four variants (opencv-python, opencv-contrib-python and their -headless versions) all provide the same cv2 module and conflict. Check pip list | grep -i opencv; a transitive dependency often pulls in the GUI variant, so pin the headless one in your own requirements, or add a constraint. 3. If you really need GUI features inside the container, install the missing system libraries in the image instead (on Debian/Ubuntu the package providing libGL.so.1 is typically libgl1, plus libglib2.0-0 for libgthread); check your distribution's package search for the exact name. 4. Rebuild the image without cache after changing packages so the old wheel isn't reused. Verify: python -c "import cv2; print(cv2.__version__)" works in the container, and pip list shows a single OpenCV package. Sources: https://github.com/opencv/opencv-python https://pypi.org/project/opencv-python/