docling-project/docling · error · ImportError

tesserocr is not correctly configured. No language models ha

Error message

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/

What it means

tesserocr.get_languages() returns the list of language models found on the system. If it comes back empty, Docling raises this ImportError: no tessdata files are discoverable, so OCR would fail for every language. The fix is to point TESSDATA_PREFIX at a directory containing *.traineddata files.

Source

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

                "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 = ""

            tesserocr_kwargs = {
                "init": True,
                "oem": tesserocr.OEM.DEFAULT,
            }

            self.osd_reader = None

            if self.options.path is not None:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install at least one language pack: apt-get install tesseract-ocr-eng (or the languages you need).
Set TESSDATA_PREFIX to the directory containing *.traineddata, e.g. /usr/share/tesseract-ocr/4.00/tessdata or /usr/local/share/tessdata.
Verify with 'ls $TESSDATA_PREFIX/*.traineddata' in the same environment your app runs in.

Example fix

# before
# ImportError: No language models have been detected

# after
$ apt-get install -y tesseract-ocr-eng
$ export TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata

Defensive patterns

Strategy: validation

Validate before calling

import tesserocr

_, langs = tesserocr.get_languages()
if not langs:
    raise SystemExit(
        "no tessdata found — install language packs and set TESSDATA_PREFIX"
    )

Try / catch

try:
    TesseractOcrModel(options=TesseractOcrOptions())
except ImportError as e:
    if "No language models have been detected" in str(e):
        os.environ["TESSDATA_PREFIX"] = "/usr/share/tesseract-ocr/4.00/tessdata"
        TesseractOcrModel(options=TesseractOcrOptions())  # retry once
    else:
        raise

Prevention

Install at least one tesseract-ocr-<lang> package alongside the binary in images.
Set and verify TESSDATA_PREFIX in deployment manifests.
Add a startup check listing *.traineddata in the configured tessdata dir.

When it happens

Trigger: Tesseract installed without any language packs, or the tessdata directory is not where tesserocr looks — TESSDATA_PREFIX unset/wrong while the default search path has no traineddata files.

Common situations: Minimal Docker images that install tesseract-ocr but not tesseract-ocr-eng; custom Tesseract builds installed to /usr/local without copying tessdata; envvar typos in deployment manifests.

Related errors

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