Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

import cv2 fails with libGL.so.1 missing in a Docker image

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

Short answer

The standard opencv-python wheel links against desktop graphics libraries that a slim Docker image does not have. Replace it with opencv-python-headless, which is built for servers and containers. If you really need GUI functions, install the libgl1 package with apt-get instead. Keep only one OpenCV variant installed.

  • Applies to Python 3.12, opencv-python 4.x, python:3.12-slim image
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List which OpenCV packages are installed. More than one variant in the same environment is its own problem.

    pip list | grep -i opencv
  2. 2Match what you see, then jump to its fix

    1. 1ImportError: libGL.so.1 on import cv2The GUI build of OpenCV is installed on a server imageFix
    2. 2The code calls imshow, or a library you use requires the non-headless wheelYou need cv2.imshow or another GUI functionFix

What does the error look like?

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

Cause 1 of 2

The GUI build of OpenCV is installed on a server image

1Check

opencv-python is the build with GUI support, and it expects graphics libraries on the system.

pip list | grep -i opencv

2Fix

Use the headless build, which has no GUI library dependency and gives a smaller image. Remove every other OpenCV variant first, because they share the cv2 name.

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

3Verify

The import works.

python -c 'import cv2; print(cv2.__version__)'

Confirmed by pypi.org

Did this fix it?

Cause 2 of 2

You need cv2.imshow or another GUI function

1Check

The headless build leaves out the GUI functions, so it is not an option here.

grep -rn "imshow\|namedWindow" .

2Fix

Install the system library that provides libGL.so.1. In Debian that file is part of the libgl1 package. Add it to the Dockerfile in one RUN line.

RUN apt-get update && apt-get install -y --no-install-recommends \
    libgl1 \
    && rm -rf /var/lib/apt/lists/*

3Verify

Rebuild and import.

docker build -t cvtest .
docker run --rm cvtest python -c "import cv2"

Confirmed by packages.debian.org

Did this fix it?

How do I stop it coming back?

  • In requirements files for servers, pin opencv-python-headless and not opencv-python.
  • Check that no dependency pulls in the full opencv-python wheel next to the headless one.
  • A container has no display anyway; save images to disk instead of calling imshow.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.