docling-project/docling · error · ImportError

ocrmac is not correctly installed. Please install it via `pi

Error message

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/

What it means

On macOS with the engine enabled, docling lazily imports ocrmac; ImportError is raised with install instructions when the package is missing, since ocrmac is an optional dependency. The message links to docling's installation docs and mentions other OCR engines as alternatives.

Source

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

        )
        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
            return

        for page in page_batch:
            assert page._backend is not None
            if not page._backend.is_valid():
                yield page
            else:
                with TimeRecorder(conv_res, "ocr"):
                    ocr_rects = self.get_ocr_rects(page)

View on GitHub (pinned to 61d76f1ff3)

Solutions

Run `pip install ocrmac` on the macOS host.
Or switch to another installed OCR engine (Tesseract, EasyOCR, RapidOCR) via pipeline_options.ocr_options.
Verify with `python -c "from ocrmac import ocrmac"`.

Example fix

# before
pipeline_options.ocr_options = OcrMacOptions()  # macOS, ocrmac missing -> ImportError

# after (terminal)
pip install ocrmac
python -c "from ocrmac import ocrmac; print('ok')"

Defensive patterns

Strategy: validation

Validate before calling

try:
    from ocrmac import ocrmac  # noqa: F401
    ocrmac_available = True
except ImportError:
    ocrmac_available = False

options = OcrMacOptions() if sys.platform == "darwin" and ocrmac_available else TesseractOcrOptions()

Prevention

Add ocrmac to your dependency set on macOS builds.
Probe imports for optional engines before selecting one.
Include optional OCR deps in the macOS CI environment to catch missing packages early.

When it happens

Trigger: Setting ocr_options = OcrMacOptions() on macOS in an environment that installed docling without the ocrmac package.

Common situations: Base `pip install docling` (no OCR extras) on a Mac; a fresh virtualenv; ocrmac removed during dependency pruning.

Related errors

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