{"record":{"id":"71c9353cb778b103","repo":"docling-project/docling","slug":"ocrmac-is-only-supported-on-mac","errorCode":null,"errorMessage":"OcrMac is only supported on Mac.","messagePattern":"OcrMac is only supported on Mac\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/ocr/ocr_mac_model.py","lineNumber":46,"sourceCode":"        enabled: bool,\n        artifacts_path: Optional[Path],\n        options: OcrMacOptions,\n        accelerator_options: AcceleratorOptions,\n    ):\n        super().__init__(\n            enabled=enabled,\n            artifacts_path=artifacts_path,\n            options=options,\n            accelerator_options=accelerator_options,\n        )\n        self.options: OcrMacOptions\n\n        # multiplier for 72 dpi; the default 3.0 == 216 dpi.\n        self.scale = self.options.scale\n\n        if self.enabled:\n            if \"darwin\" != sys.platform:\n                raise RuntimeError(\"OcrMac is only supported on Mac.\")\n            install_errmsg = (\n                \"ocrmac is not correctly installed. \"\n                \"Please install it via `pip install ocrmac` to use this OCR engine. \"\n                \"Alternatively, Docling has support for other OCR engines. See the documentation: \"\n                \"https://docling-project.github.io/docling/installation/\"\n            )\n            try:\n                from ocrmac import ocrmac\n            except ImportError:\n                raise ImportError(install_errmsg)\n\n            self.reader_RIL = ocrmac.OCR\n\n    def __call__(\n        self, conv_res: ConversionResult, page_batch: Iterable[Page]\n    ) -> Iterable[Page]:\n        if not self.enabled:\n            yield from page_batch","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/ocr/ocr_mac_model.py#L28-L64","documentation":"The OcrMac OCR engine wraps Apple's macOS Vision framework, which only exists on Darwin. On construction with enabled=True, the stage checks sys.platform and raises RuntimeError on any non-macOS OS before attempting the import. This is a hard platform gate, not an optional capability.","triggerScenarios":"Constructing a pipeline with OcrMacOptions on Linux or Windows — the check fires immediately in __init__ when enabled is True.","commonSituations":"Developing cross-platform code with a shared config that pins ocr_options to OcrMac; deploying a Mac-tested pipeline to Linux servers or Docker containers.","solutions":["Select the OCR engine conditionally: use OcrMac only when sys.platform == 'darwin', otherwise Tesseract/EasyOCR/RapidOCR.","Keep OCR choice in per-platform config files rather than one shared literal options object.","In containers (even on a Mac, containers are Linux), never enable OcrMac."],"exampleFix":"# before\nfrom docling.models.stages.ocr.ocr_mac_model import OcrMacOptions\npipeline_options.ocr_options = OcrMacOptions()  # on Linux -> RuntimeError\n\n# after\nimport sys\nif sys.platform == \"darwin\":\n    pipeline_options.ocr_options = OcrMacOptions()\nelse:\n    from docling.models.stages.ocr.tesseract_ocr_model import TesseractOcrOptions\n    pipeline_options.ocr_options = TesseractOcrOptions()","handlingStrategy":"validation","validationCode":"import sys\n\nif sys.platform == \"darwin\":\n    pipeline_options.ocr_options = OcrMacOptions()\nelse:\n    pipeline_options.ocr_options = TesseractOcrOptions()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never enable OcrMac in Linux/Windows containers or CI runners — check sys.platform first.","Keep per-platform config files for OCR engine selection.","Remember containers on macOS hosts report 'linux'; use the host Python for OcrMac."],"tags":["ocrmac","ocr","platform","macos"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}