docling-project/docling · error · ImportError

tesserocr is not correctly installed. Please install it via

Error message

tesserocr is not correctly installed. Please install it via `pip install tesserocr` to use this OCR engine. Note that tesserocr might have to be manually compiled for working with your Tesseract installation. The Docling documentation provides examples for it. Alternatively, Docling has support for other OCR engines. See the documentation: https://docling-project.github.io/docling/installation/

What it means

The tesserocr-based (C API) Tesseract model imports the tesserocr Python package at init. If the import fails, Docling raises this ImportError telling you to install tesserocr and noting it may need manual compilation against your Tesseract libraries, with a pointer to the Docling installation docs.

Source

Thrown at docling/models/stages/ocr/tesseract_ocr_model.py:70

                "tesserocr is not correctly installed. "
                "Please install it via `pip install tesserocr` to use this OCR engine. "
                "Note that tesserocr might have to be manually compiled for working with "
                "your Tesseract installation. The Docling documentation provides examples for it. "
                "Alternatively, Docling has support for other OCR engines. See the documentation: "
                "https://docling-project.github.io/docling/installation/"
            )
            missing_langs_errmsg = (
                "tesserocr is not correctly configured. No language models have been detected. "
                "Please ensure that the TESSDATA_PREFIX envvar points to tesseract languages dir. "
                "You can find more information how to setup other OCR engines in Docling "
                "documentation: "
                "https://docling-project.github.io/docling/installation/"
            )

            try:
                import tesserocr
            except ImportError:
                raise ImportError(install_errmsg)
            try:
                tesseract_version = tesserocr.tesseract_version()
            except Exception:
                raise ImportError(install_errmsg)

            _, self._tesserocr_languages = tesserocr.get_languages()
            if not self._tesserocr_languages:
                raise ImportError(missing_langs_errmsg)

            # Initialize the tesseractAPI
            _log.debug("Initializing TesserOCR: %s", tesseract_version)
            lang = "+".join(self.options.lang)

            if any(lang.startswith("script/") for lang in self._tesserocr_languages):
                self.script_prefix = "script/"
            else:
                self.script_prefix = ""

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install tesserocr: pip install tesserocr (or conda install -c conda-forge tesserocr, which bundles matching Tesseract).
If compilation fails, ensure the system Tesseract dev headers (libtesseract-dev, libleptonica-dev) and pkg-config are installed, or use the conda-forge package.
Alternatively switch to the CLI-based engine (tesseract binary on PATH) or another OCR engine supported by Docling.

Example fix

# before
# ImportError: tesserocr is not correctly installed

# after
$ conda install -c conda-forge tesserocr
# or switch engine:
pipeline_options.ocr_options = TesseractCliOcrOptions()

Defensive patterns

Strategy: validation

Validate before calling

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

if not tesserocr_available():
    raise SystemExit("tesserocr missing: pip install tesserocr (see docling docs)")

Try / catch

try:
    TesseractOcrModel(options=TesseractOcrOptions())
except ImportError as e:
    if "tesserocr is not correctly installed" in str(e):
        # fall back to the CLI engine, which only needs the binary
        from docling.models.stages.ocr.tesseract_ocr_cli_model import TesseractOcrCliModel
        model = TesseractOcrCliModel(options=TesseractCliOcrOptions())
    else:
        raise

Prevention

Prefer conda-forge for matched tesseract/tesserocr installs.
Smoke-test 'import tesserocr; tesserocr.tesseract_version()' in your build pipeline.
Keep a CLI-engine fallback path for environments where the C extension cannot build.

When it happens

Trigger: pipeline_options.ocr_options = TesseractOcrOptions() (the tesserocr engine) in an environment where 'import tesserocr' raises ImportError — package not installed, or installed for a mismatched Python/ABI.

Common situations: docling-slim installs without OCR extras; pip-installed tesserocr wheel built against a different Tesseract version; conda/pip interpreter mixups where the package landed in another env.

Related errors

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