docling-project/docling · error · RuntimeError

Tesseract is not available, aborting: {exc} Install tesserac

Error message

Tesseract is not available, aborting: {exc} Install tesseract on your system and the tesseract binary is discoverable. The actual command for Tesseract can be specified in `pipeline_options.ocr_options.tesseract_cmd='tesseract'`. Alternatively, Docling has support for other OCR engines. See the documentation.

What it means

The CLI-based Tesseract OCR model runs 'tesseract --version' and reads available languages at init. Any exception there (binary not found, not executable, version output unparsable, requested language packs missing) is wrapped in this RuntimeError with remediation hints, including the tesseract_cmd override.

Source

Thrown at docling/models/stages/ocr/tesseract_ocr_cli_model.py:83

        # so that all subsequent subprocess calls use only these already-validated values.
        self._safe_tesseract_cmd: str = self._sanitize_cmd(self.options.tesseract_cmd)
        self._safe_tessdata_path: Optional[str] = (
            self._sanitize_path(self.options.path)
            if self.options.path is not None
            else None
        )
        if self.options.lang:
            for _lang_token in self.options.lang:
                if _lang_token != "auto":
                    self._sanitize_lang(_lang_token)

        if self.enabled:
            try:
                self._get_name_and_version()
                self._set_languages_and_prefix()

            except Exception as exc:
                raise RuntimeError(
                    f"Tesseract is not available, aborting: {exc} "
                    "Install tesseract on your system and the tesseract binary is discoverable. "
                    "The actual command for Tesseract can be specified in `pipeline_options.ocr_options.tesseract_cmd='tesseract'`. "
                    "Alternatively, Docling has support for other OCR engines. See the documentation."
                )

    @staticmethod
    def _sanitize_lang(lang: str) -> str:
        """Validate and sanitize a Tesseract language identifier to prevent argument injection.

        Valid identifiers (e.g. ``eng``, ``script/Latin``, ``eng+deu``) contain only
        alphanumeric characters, underscores, hyphens, forward slashes, and plus signs.
        """
        if not _VALID_LANG_RE.match(lang):
            raise ValueError(
                f"Invalid Tesseract language identifier: {lang!r}. "
                "Language identifiers must only contain alphanumeric characters, "
                "underscores, hyphens, forward slashes, and plus signs."

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install Tesseract on the system (apt-get install tesseract-ocr, brew install tesseract, or choco install tesseract) and ensure 'tesseract --version' works in the same shell.
If installed at a custom location, point Docling at it: pipeline_options.ocr_options.tesseract_cmd = '/usr/local/bin/tesseract'.
Alternatively pick a different OCR engine (e.g. RapidOCR) or install the docling extras that bundle an engine.

Example fix

# before
# RuntimeError: Tesseract is not available (binary not on PATH)

# after
$ apt-get install -y tesseract-ocr
# or in code:
pipeline_options.ocr_options.tesseract_cmd = "/usr/local/bin/tesseract"

Defensive patterns

Strategy: validation

Validate before calling

import shutil, subprocess

cmd = tesseract_cmd or "tesseract"
if shutil.which(cmd) is None:
    raise SystemExit(f"tesseract binary {cmd!r} not found on PATH")
subprocess.run([cmd, "--version"], capture_output=True, check=True)

Try / catch

try:
    TesseractOcrCliModel(options=TesseractCliOcrOptions())
except RuntimeError as e:
    if "Tesseract is not available" in str(e):
        log.error("install tesseract or set tesseract_cmd: %s", e)
        raise
    raise

Prevention

Install tesseract in your base Docker image and smoke-test 'tesseract --version' in CI.
Set tesseract_cmd explicitly in containers to avoid PATH surprises.
Add the needed language packs (e.g. tesseract-ocr-eng) alongside the binary.

When it happens

Trigger: pipeline_options.ocr_options = TesseractOcrOptions() with the tesseract binary absent from PATH; tesseract_cmd pointing to a wrong location; or the system tesseract install broken so that --version or language listing fails.

Common situations: Slim Docker images / CI runners without the tesseract package; macOS/Windows where tesseract is installed but not on PATH; custom tesseract builds installed at non-standard locations.

Related errors

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