What causes "OcrMac is only supported on Mac." in docling-project/docling?

Select the OCR engine conditionally: use OcrMac only when sys.platform == 'darwin', otherwise Tesseract/EasyOCR/RapidOCR.

docling-project/docling · error · RuntimeError

OcrMac is only supported on Mac.

Error message

OcrMac is only supported on Mac.

What it means

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.

Source

Thrown at docling/models/stages/ocr/ocr_mac_model.py:46

        enabled: bool,
        artifacts_path: Optional[Path],
        options: OcrMacOptions,
        accelerator_options: AcceleratorOptions,
    ):
        super().__init__(
            enabled=enabled,
            artifacts_path=artifacts_path,
            options=options,
            accelerator_options=accelerator_options,
        )
        self.options: OcrMacOptions

        # multiplier for 72 dpi; the default 3.0 == 216 dpi.
        self.scale = self.options.scale

        if self.enabled:
            if "darwin" != sys.platform:
                raise RuntimeError("OcrMac is only supported on Mac.")
            install_errmsg = (
                "ocrmac is not correctly installed. "
                "Please install it via `pip install ocrmac` to use this OCR engine. "
                "Alternatively, Docling has support for other OCR engines. See the documentation: "
                "https://docling-project.github.io/docling/installation/"
            )
            try:
                from ocrmac import ocrmac
            except ImportError:
                raise ImportError(install_errmsg)

            self.reader_RIL = ocrmac.OCR

    def __call__(
        self, conv_res: ConversionResult, page_batch: Iterable[Page]
    ) -> Iterable[Page]:
        if not self.enabled:
            yield from page_batch

View on GitHub (pinned to 61d76f1ff3)

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.

Example fix

# before
from docling.models.stages.ocr.ocr_mac_model import OcrMacOptions
pipeline_options.ocr_options = OcrMacOptions()  # on Linux -> RuntimeError

# after
import sys
if sys.platform == "darwin":
    pipeline_options.ocr_options = OcrMacOptions()
else:
    from docling.models.stages.ocr.tesseract_ocr_model import TesseractOcrOptions
    pipeline_options.ocr_options = TesseractOcrOptions()

Defensive patterns

Strategy: validation

Validate before calling

import sys

if sys.platform == "darwin":
    pipeline_options.ocr_options = OcrMacOptions()
else:
    pipeline_options.ocr_options = TesseractOcrOptions()

Prevention

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.

When it happens

Trigger: Constructing a pipeline with OcrMacOptions on Linux or Windows — the check fires immediately in __init__ when enabled is True.

Common situations: 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.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/71c9353cb778b103. Report an issue: GitHub.