From 1f67fa64bf51fcb16f18415e5eb5074d475c378b Mon Sep 17 00:00:00 2001
From: Ruchitha K P <ruchithakp74@gmail.com>
Date: Tue, 2 Dec 2025 18:57:26 +0530
Subject: [PATCH 1/2] docs: add troubleshooting guide for OpenCV GUI backend
 errors

---
 docs/gui-backend-issues.md | 114 +++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docs/gui-backend-issues.md

diff --git a/docs/gui-backend-issues.md b/docs/gui-backend-issues.md
new file mode 100644
index 00000000..67f839f3
--- /dev/null
+++ b/docs/gui-backend-issues.md
@@ -0,0 +1,114 @@
+# Troubleshooting OpenCV GUI Backend Errors
+### (`cv2.imshow`, `libGL.so.1`, HighGUI backend not available)
+
+Many Python users encounter GUI-related errors when using OpenCV functions such as  
+`cv2.imshow()`, `cv2.namedWindow()`, or `cv2.waitKey()`.  
+These errors often appear in **headless environments** such as:
+
+- CI/CD pipelines  
+- Docker containers  
+- Cloud servers  
+- WSL  
+- Google Colab  
+- SSH sessions  
+
+This guide explains:
+
+- Common GUI error messages  
+- Why these errors occur  
+- How to fix them on Linux, Windows, Docker, CI/CD, WSL  
+- When to use `opencv-python` vs. `opencv-python-headless`
+
+---
+
+## 1. Common Error Messages
+
+```
+ImportError: libGL.so.1: cannot open shared object file
+cv2.error: (-2:Unspecified error) The function is not implemented
+error: (-215:Assertion failed) size.width>0 in function 'imshow'
+HighGUI backend error: No available GUI backend
+```
+
+These errors occur because OpenCV cannot access the required **GUI backend** for creating display windows.
+
+---
+
+## 2. Why GUI Errors Occur
+
+OpenCV uses **HighGUI** for display functions (`imshow`, `waitKey`, etc.).  
+These depend on external system libraries such as:
+
+- `libGL` (OpenGL)
+- GTK or Qt
+- X11 display server
+- Cocoa (macOS)
+- Windows native GUI APIs
+
+Headless systems **do not include** these libraries, causing GUI errors when you attempt display operations.
+
+Common environments without GUI support:
+
+- GitHub/GitLab CI
+- Docker containers
+- Linux servers
+- Google Colab
+- WSL (Windows Subsystem for Linux)
+- SSH-only sessions
+
+---
+
+## 3. Fixes for Linux Desktop
+
+If you are on a regular Linux machine **with GUI**, install missing dependencies:
+
+```bash
+sudo apt update
+sudo apt install -y libgl1-mesa-glx libglib2.0-0
+sudo apt install -y libgtk2.0-dev libgtk-3-dev
+```
+## 4. Fixes for Windows
+
+Most GUI issues on Windows come from incomplete or corrupted installations.
+Reinstall OpenCV:
+```bash
+pip install --upgrade opencv-python
+pip install --upgrade opencv-contrib-python
+```
+⚠️ Important:
+Do NOT install opencv-python-headless on Windows if you want GUI support.
+
+## 5. Fixes for Headless Environments(CI, Docker, Colab, Servers)
+
+In headless environments, **cv2.imshow()** will never work.
+
+Install the headless version instead:
+```bash
+pip install opencv-python-headless
+```
+Use file-based output instead of GUI display:
+```python
+import cv2
+img = cv2.imread("image.jpg")
+cv2.imwrite("output.jpg", img)
+```
+## 6. Fix for Docker
+
+Add GUI dependencies to your Dockerfile:
+```dockerfile
+RUN apt-get update && \
+    apt-get install -y libgl1-mesa-glx libglib2.0-0
+```
+For headless images:
+```bash
+pip install opencv-python-headless
+
+## 7. Fix For CI/CD(GitHub Actions)
+
+```
+- name: Install OpenCV GUI dependencies
+  run: |
+    sudo apt-get update
+    sudo apt-get install -y libgl1-mesa-glx libglib2.0-0
+```
+

From d9c218aa23354fd1a87d14f57699871e8558ac17 Mon Sep 17 00:00:00 2001
From: Ruchitha K P <ruchithakp74@gmail.com>
Date: Tue, 2 Dec 2025 19:06:45 +0530
Subject: [PATCH 2/2] docs: fix formatting and text in gui-backend-issues.md

---
 docs/gui-backend-issues.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/gui-backend-issues.md b/docs/gui-backend-issues.md
index 67f839f3..ce7edb31 100644
--- a/docs/gui-backend-issues.md
+++ b/docs/gui-backend-issues.md
@@ -102,7 +102,7 @@ RUN apt-get update && \
 For headless images:
 ```bash
 pip install opencv-python-headless
-
+```
 ## 7. Fix For CI/CD(GitHub Actions)
 
 ```