docling-project/docling · error · ImportError

RapidOCR is not installed. Please install it via `pip instal

Error message

RapidOCR is not installed. Please install it via `pip install rapidocr onnxruntime` to use this OCR engine. Alternatively, Docling has support for other OCR engines. See the documentation.

What it means

When RapidOCR is the enabled OCR engine, Docling imports rapidocr at model initialization. If the import fails (package not installed in this environment), it raises this ImportError with installation guidance instead of a raw ModuleNotFoundError.

Source

Thrown at docling/models/stages/ocr/rapid_ocr_model.py:281

        options: RapidOcrOptions,
        accelerator_options: AcceleratorOptions,
    ):
        super().__init__(
            enabled=enabled,
            artifacts_path=artifacts_path,
            options=options,
            accelerator_options=accelerator_options,
        )
        self.options: RapidOcrOptions

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

        if self.enabled:
            try:
                from rapidocr import ModelType, OCRVersion, RapidOCR  # type: ignore
            except ImportError:
                raise ImportError(
                    "RapidOCR is not installed. Please install it via `pip install rapidocr onnxruntime` to use this OCR engine. "
                    "Alternatively, Docling has support for other OCR engines. See the documentation."
                )

            # Decide the accelerator devices
            device = decide_device(accelerator_options.device)
            use_cuda = str(AcceleratorDevice.CUDA.value).lower() in device
            use_dml = accelerator_options.device == AcceleratorDevice.AUTO
            intra_op_num_threads = accelerator_options.num_threads
            gpu_id = 0
            if use_cuda and ":" in device:
                gpu_id = int(device.split(":")[1])
            backend_enum = _backend_to_engine_type(self.options.backend)

            # Reduce the user provided language list to one language
            lang = (
                self.options.lang[0]
                if self.options.lang

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install the engine: pip install rapidocr onnxruntime (or add the appropriate docling extras).
If you did not intend to use RapidOCR, switch the OCR engine, e.g. OcrOptions(ocr_engine='tesseract'), or disable OCR.
Verify with 'python -c "import rapidocr"' in the same interpreter/venv your application runs in.

Example fix

# before (env lacks rapidocr)
# pipeline with RapidOcrOptions fails at init

# after
$ pip install rapidocr onnxruntime
# or: switch engine
pipeline_options.ocr_options = OcrOptions(ocr_engine="tesseract")

Defensive patterns

Strategy: validation

Validate before calling

def rapidocr_available() -> bool:
    try:
        import rapidocr  # noqa: F401
        return True
    except ImportError:
        return False

if ocr_engine == "rapidocr" and not rapidocr_available():
    raise SystemExit("rapidocr missing: pip install rapidocr onnxruntime")

Try / catch

try:
    pipeline.initialize()
except ImportError as e:
    if "RapidOCR is not installed" in str(e):
        # degrade gracefully: disable OCR or switch engine
        pipeline_options.ocr_options.enabled = False
        pipeline.initialize()
    else:
        raise

Prevention

Declare OCR extras in your deployment's dependency manifest (requirements/lockfile).
Smoke-test 'import rapidocr' in the target container image during build.
Use docling full package (not slim) when OCR is required.

When it happens

Trigger: Running the pipeline with RapidOcrOptions as the OCR engine (or default resolution picking RapidOCR) in an environment where 'rapidocr' and/or its runtime (e.g. onnxruntime) is missing. Common with docling-slim installs or minimal virtualenvs.

Common situations: Using docling-slim without OCR extras; installing rapidocr but not onnxruntime (torch/onnxruntime backends need their runtime dependency); CI images trimmed of optional OCR dependencies.

Related errors

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