{"record":{"id":"0d7a0b7406201072","repo":"deepinsight/insightface","slug":"opencv-is-required-for-video-face-swap-exc","errorCode":null,"errorMessage":"OpenCV is required for video face swap: {exc}","messagePattern":"OpenCV is required for video face swap: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/pages/face_swap_page.py","lineNumber":234,"sourceCode":"        target_face = self.context.engine.detect_best_face(target_image, source_path=target_path)\n        if target_face is None or target_face.kps is None:\n            raise ValueError(\"No usable face detected in target image.\")\n        target_native = SimpleNamespace(kps=np.asarray(target_face.kps, dtype=np.float32))\n        image = swapper.swap(target_image, target_native, source_native)\n        output_path = Path(self.context.config.export_dir) / f\"face_swap_{timestamp_for_filename()}.png\"\n        save_image(output_path, image)\n        return {\n            \"kind\": \"image\",\n            \"image\": image,\n            \"path\": str(output_path),\n            \"message\": f\"Image face swap saved to {output_path}\",\n        }\n\n    def _swap_video(self, swapper: FaceSwapEngine, source_native, target_path: str, progress=None, is_cancelled=None) -> dict:\n        try:\n            import cv2\n        except Exception as exc:\n            raise ValueError(f\"OpenCV is required for video face swap: {exc}\") from exc\n\n        cap = cv2.VideoCapture(target_path)\n        if not cap.isOpened():\n            raise ValueError(\"Video could not be opened.\")\n        fps = cap.get(cv2.CAP_PROP_FPS) or 25.0\n        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)\n        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)\n        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)\n        if width <= 0 or height <= 0:\n            cap.release()\n            raise ValueError(\"Video dimensions could not be read.\")\n        output_path = Path(self.context.config.export_dir) / f\"face_swap_video_{timestamp_for_filename()}.mp4\"\n        output_path.parent.mkdir(parents=True, exist_ok=True)\n        writer = cv2.VideoWriter(str(output_path), cv2.VideoWriter_fourcc(*\"mp4v\"), fps, (width, height))\n        if not writer.isOpened():\n            cap.release()\n            raise ValueError(\"Video writer could not be opened.\")\n","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/pages/face_swap_page.py#L216-L252","documentation":"Thrown when the cv2 (OpenCV) import inside _swap_video fails; video face swap requires OpenCV for VideoCapture/VideoWriter, and the import exception is chained into the ValueError message.","triggerScenarios":"Starting a video face swap in an environment where cv2 is not installed, or where importing cv2 raises (broken install, missing libGL/libgthread shared libraries on Linux).","commonSituations":"Headless Linux containers missing libgl1 causing 'cv2.error: libGL.so.1 cannot be opened', partial pip installs, opencv-python uninstalled as a dependency conflict resolution.","solutions":["Read the chained {exc} text: if libGL.so.1 missing, install system package libgl1 (and libglib2.0-0)","pip install opencv-python (or use opencv-python-headless in servers/containers)","Reinstall cleanly: pip uninstall opencv-python opencv-python-headless -y then install one variant","Verify with python -c \"import cv2\" before retrying"],"exampleFix":"# before (container)\n# pip install opencv-python -> import fails on libGL\n# after\npip install opencv-python-headless\n# or: apt-get install -y libgl1 libglib2.0-0","handlingStrategy":"validation","validationCode":"try:\n    import cv2  # noqa\nexcept Exception:\n    disable_video_tab_with_message('pip install opencv-python')","typeGuard":null,"tryCatchPattern":"try:\n    return self._swap_video(...)\nexcept ValueError as e:\n    if 'OpenCV is required' in str(e): run_pip('opencv-python-headless')","preventionTips":["Declare opencv as a hard dependency if video features ship","Use opencv-python-headless in GUI-less deployments","Smoke-test `import cv2` during environment setup"],"tags":["insightface","opencv","cv2","import-error","video"],"backgroundTag":"opencv-import-libgl-error","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}