Docling OCR Engines

OCR is on by default (--ocr). Three flags control where it runs and which engine runs it:

Python equivalent: PdfPipelineOptions().do_ocr = True plus one of RapidOcrOptions / EasyOcrOptions / TesseractOcrOptions / TesseractCliOcrOptions / OcrMacOptions / NemotronOcrOptions with mode=OcrMode.FULL_PAGE when you want full-page behavior. Debug what OCR sees with --debug-visualize-ocr.

Tesseract system binary per OS

Windows: install the UB Mannheim build, add it to PATH, and set TESSDATA_PREFIX to its tessdata\ folder. If tesserocr fails to compile: pip uninstall tesserocr, then pip install --no-binary :all: tesserocr. Full per-OS steps live in the install hub and OS guides.

Pre-download OCR models for offline or CI machines: docling-tools models download --all, or targeted --easyocr-lang de / --rapidocr-backend-lang onnxruntime:el. See the CLI reference.

RapidOCR wraps PP-OCR models. Two things vary independently: the backend (runtime) and the PP-OCR version (model generation).

Backends

Language tokens (native codes)

• v4: arabic, ch, chinese_cht, cyrillic, devanagari, en, japan, ka, korean, latin, ta, te.
• v5: arabic, ch, cyrillic, devanagari, el, en, eslav, korean, latin, ta, te, th.
• v6: ch, chinese_cht, en, japan + ~45 European codes (de, fr, es, it, pt, nl, pl …) with aliases zh→ch, zh_cn→ch, zh_tw→chinese_cht, ja/jp→japan, ko→korean (note: Korean has only the alias in v6). de/german and fr/french both exist.
• Script families (one token covers many languages): cyrillic (34: Russian, Ukrainian, Kazakh … + English), devanagari (14: Hindi, Marathi, Sanskrit … + English), arabic (9: Arabic, Persian, Urdu … + English), eslav (East Slavic: Russian, Belarusian, Ukrainian + English).

Single language per run: RapidOCR uses the first lang entry and warns about the rest. Python: RapidOcrOptions(lang=["eslav"], backend="onnxruntime"); custom checkpoints are supported (see the custom-models example).

EasyOCR (gen2 checkpoints, craft_mlt_25k.pth detector) accepts several languages at once — but resolution picks the single checkpoint covering all requested languages.

• Two flavors, one engine: tesseract shells out to the system CLI (no pip extra); tesserocr binds the library in-process (faster, needs the compiled binding). Same accuracy, same traineddata.
• Language = traineddata stem: deu, chi_sim, chi_tra, srp_latn, aze_cyrl, deu_latf, frk, jpn_vert, script/Latin, script/Cyrillic — plus any file you trained yourself. Whatever .traineddata files are installed is what you can use.
• Checked at construction time: missing files fail immediately with the installed set in the error message — not mid-conversion.
• Empty lang = script detection: --ocr-lang "" runs per-page orientation/script detection, which requires the osd traineddata file.
• Auto language detection is demonstrated in the official example.

OcrMac is a thin wrapper over Apple’s Vision framework: no binaries, no downloadable models — the recognizers ship with the OS, so the supported language set is a property of your macOS version, not the ocrmac release.

• Install: pip install "docling[ocrmac]"; Python: OcrMacOptions.
• Matching is by BCP-47 with regions: iso:de finds de-DE, iso:pt finds pt-BR, iso:zh-CN finds zh-Hans.
• Odd region codes like vi-VT must be passed bare (native). Empty lang lets Vision choose automatically.

Requires Linux x86_64 with CUDA 13.x and the cu130 torch index (install line in section 4). Single language per run (first entry wins). Python: NemotronOcrOptions.

• KServe v2: for teams whose OCR runs as a remote microservice. lang is neither validated nor mapped — the first entry is sent verbatim, the rest dropped with a warning. Use whatever codes your deployment expects; iso: only works if the server speaks it (none do).
• OnnxTR plugin: pip install "docling-ocr-onnxtr[cpu]", enable --allow-external-plugins, select with the plugin’s engine name. See the docling-OCR-OnnxTR repo.
• SuryaOCR with custom models is demonstrated in the official example; list third-party options with --show-external-plugins.

Every engine takes languages through one field, OcrOptions.lang. Each entry has exactly two forms:

• Native code (no prefix) — the engine’s own spelling, passed through verbatim: ch (PP-OCR Chinese), deu (Tesseract German), ch_sim (EasyOCR), en-US (Vision).
• Portable tag — BCP-47 behind iso:, mapped onto the engine: iso:de, iso:en-US, iso:zh-Hant. Always include the script when it is non-default: Serbian Latin must be iso:sr-Latn (default Serbian is Cyrillic).

from docling.datamodel.pipeline_options import TesseractCliOcrOptions
TesseractCliOcrOptions(lang=["deu", "eng"])       # native: tesseract -l deu+eng
TesseractCliOcrOptions(lang=["iso:de", "iso:en"]) # portable: same thing

Tags Docling refuses

What an empty language list means per engine

Codes that shadow a language tag (write carefully)

A few bare codes mean something different from the same BCP-47 subtag. Bare = the model; iso: = the language:

Ask any engine what it serves: supported_ocr_languages() returns native + BCP-47 codes in a spelling you can paste back into lang. Docling never silently substitutes — an unservable language raises, naming what the engine can serve. RapidOCR and Nemotron run one language at a time (first tag wins, rest warn).

• RapidOCR on CUDA: install the GPU ONNX Runtime — pip install "docling[onnxruntime]" — confirm CUDAExecutionProvider is in ort.get_available_providers(), then use the onnxruntime backend with a CUDA device. The torch backend is the alternative (remember: PP-OCRv5 + torch = Chinese only).

import onnxruntime as ort
assert "CUDAExecutionProvider" in ort.get_available_providers()

from docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions
from docling.datamodel.pipeline_options import PdfPipelineOptions, RapidOcrOptions
pipeline_options = PdfPipelineOptions(
    accelerator_options=AcceleratorOptions(device=AcceleratorDevice.CUDA),
    ocr_options=RapidOcrOptions(backend="onnxruntime", lang=["eslav"]),
)

• Nemotron is GPU-only by design (CUDA 13.x, Linux x86_64).
• EasyOCR / Tesseract / OcrMac are effectively CPU-bound — put them on a fast CPU and spend GPU budget on layout/table stages instead. Full tuning (batch sizes, VLM servers) is in the official GPU guide.

Scanned PDF, full-page OCR

Pick an engine explicitly

Skip OCR for digital PDFs (fastest)

OCR in German + English, portable tags

Python: full-page OCR with backend choice

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
    OcrMode, PdfPipelineOptions, RapidOcrOptions,
)
from docling.document_converter import DocumentConverter, PdfFormatOption

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = RapidOcrOptions(mode=OcrMode.FULL_PAGE)
# Swap in EasyOcrOptions / TesseractOcrOptions / TesseractCliOcrOptions
# / OcrMacOptions (macOS) / NemotronOcrOptions (Linux CUDA) as needed.

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
doc = converter.convert("scan.pdf").document
print(doc.export_to_markdown())

More worked examples: force full-page OCR, Tesseract language detection, RapidOCR custom models, local examples library, and the config generator.

• Scanned text not recognized — OCR is off or the default mode missed the missing text layer: force --ocr-mode full_page, try another engine. See OCR a scanned PDF.
• OCR extra won’t install — RapidOCR/EasyOCR are pip-only; Tesseract needs the system binary + TESSDATA_PREFIX first. See OCR package installation error.
• Conversion is slow — OCR + enrichment models are the costliest CPU stages: --no-ocr for digital PDFs, --table-mode fast, or a GPU. See conversion is slow.
• GPU ignored — confirm torch.cuda.is_available() / CUDAExecutionProvider, use --device cuda (mps on Apple Silicon). See GPU not used.
• Wrong language output — check shadowing (ka vs iso:ka-Geor), keep EasyOCR lists short, and verify with supported_ocr_languages().