docling-project/docling · error · ImportError

EasyOCR is not installed. Please install it via `pip install

Error message

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

What it means

The EasyOCR stage lazily imports easyocr inside __init__ when enabled. If the import fails, docling raises ImportError telling you to `pip install easyocr`, since easyocr is an optional dependency not bundled with docling core. The message also points to docling's other OCR engines as alternatives.

Source

Thrown at docling/models/stages/ocr/easyocr_model.py:98

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

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

        if self.enabled:
            try:
                import easyocr
            except ImportError:
                raise ImportError(
                    "EasyOCR is not installed. Please install it via `pip install easyocr` to use this OCR engine. "
                    "Alternatively, Docling has support for other OCR engines. See the documentation."
                )

            if self.options.use_gpu is None:
                device = decide_device(accelerator_options.device)
                # Enable easyocr GPU if running on CUDA, MPS
                use_gpu = any(
                    device.startswith(x)
                    for x in [
                        AcceleratorDevice.CUDA.value,
                        AcceleratorDevice.MPS.value,
                    ]
                )
            else:
                warnings.warn(
                    "Deprecated field. Better to set the `accelerator_options.device` in `pipeline_options`. "
                    "When `use_gpu and accelerator_options.device == AcceleratorDevice.CUDA` the GPU is used "

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install easyocr: `pip install easyocr` (or add it to your project dependencies / use the docling extra that includes it).
Alternatively switch to another OCR engine that is installed (Tesseract, RapidOCR, OcrMac on macOS) by changing ocr_options.
Verify with `python -c "import easyocr"` after installation.

Example fix

# before
options = EasyOcrOptions()  # enabled, easyocr missing -> ImportError at pipeline build

# after (terminal)
pip install easyocr
# or switch engine
from docling.models.stages.ocr.tesseract_ocr_model import TesseractOcrOptions
pipeline_options.ocr_options = TesseractOcrOptions()

Defensive patterns

Strategy: validation

Validate before calling

try:
    import easyocr  # noqa: F401
    easyocr_available = True
except ImportError:
    easyocr_available = False

options = EasyOcrOptions() if easyocr_available else TesseractOcrOptions()

Prevention

Declare easyocr in your project dependencies when the pipeline uses it.
Gate OCR engine choice on import availability the way docling core does.
Include optional OCR extras in Dockerfiles/CI environments to avoid runtime surprises.

When it happens

Trigger: Enabling EasyOcrOptions without easyocr installed: `pipelines_options.ocr_options = EasyOcrOptions(...)` in an environment that only has docling/docling-slim base dependencies.

Common situations: Installing docling-slim or docling without the OCR extra; a fresh virtualenv where the optional dependency was never added; CI images trimmed of optional packages.

Related errors

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