import cv2 fails with libGL.so.1 missing in a Docker image
ImportError: libGL.so.1: cannot open shared object file: No such file or directoryShort 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.
Fix it fast
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 opencv2Match what you see, then jump to its fix
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 opencv2Fix
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-headless3Verify
The import works.
python -c 'import cv2; print(cv2.__version__)'Confirmed by pypi.org
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
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
pip install cryptography tries to compile and fails in a Docker build
fatal error: 'openssl/aes.h' file not found
cryptography ships prebuilt wheels.
3 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
Docker cannot find manage.py or Permission denied on '/manage.py'
PermissionError: [Errno 13] Permission denied: '/manage.py'
The container is looking for manage.py in a directory where the file is not.
3 causes, each with a fixServers
Compose cannot start the service: exec "python manage.py runserver" failed
starting container process caused: exec: "python manage.py runserver
The container runtime was asked to run a program literally named 'python manage.py runserver', including the spaces.
2 causes, each with a fixServers
docker logs prints nothing for a Flask or Python container
the output appears only after the app exits, or in large delayed bursts
docker logs only shows what the process writes to standard output and standard error.
2 causes, each with a fix