OCR in Docling — the right engine, the right language, or none

Do you need OCR at all?#

Open the PDF and try to select a sentence. If you can, the PDF has a text layer and Docling reads it directly — exact characters, no OCR needed. In that case OCR only adds text found inside images, at a high price:

The extra 5,000 characters came from screenshots inside the paper's figures. Keep OCR when such text matters; otherwise switch it off.

Pick an engine#

The engines#

Engine list and default languages read from docling options ocr <engine> in 2.148.0. Licences of the engine packages: RapidOCR, EasyOCR and Nemotron OCR are Apache-2.0; tesserocr and ocrmac are MIT; Tesseract itself is Apache-2.0.

How auto chooses

1. macOS: ocrmac, if installed.
2. Linux with CUDA: Nemotron OCR, if installed.
3. RapidOCR with onnxruntime, if onnxruntime is installed.
4. EasyOCR, if installed.
5. RapidOCR with PyTorch — what a plain pip install docling ends up using.

Engines that cannot serve the requested language are skipped. Tesseract is never chosen automatically — select it with --ocr-engine tesseract. Order read from auto_ocr_model.py in 2.148.0; our test runs confirmed the last step on Linux.

Languages#

--ocr-lang accepts the engine's own codes, or BCP-47 tags behind iso:, which Docling translates for the chosen engine. An empty value (--ocr-lang '') lets the engine decide.

• RapidOCR runs one language per run; extra languages are ignored with a warning. Its PyTorch backend only has script-level models for many languages — on the default install we got OcrLanguageNotSupportedError for iso:ru and had to use cyrillic. * eslav was rejected the same way; en, latin, ch, chinese_cht, japan and cyrillic all ran on the PyTorch backend in our tests.
• Tesseract combines languages in the order given (deu,eng) and needs the matching traineddata installed; a missing one raises an error when the engine starts.
• EasyOCR runs several languages at once if they share a script family.

OCR modes#

Definitions from the OcrMode enum in 2.148.0.

Replace a broken text layer (new in 2.144.0)#

Some PDFs look perfect on screen, but their text copies out as nonsense — 8VceZWZTReV instead of Certificate — because a font maps its glyphs to the wrong characters. OCR modes do not help here: the default mode trusts the PDF text, and full_page throws the text layer away on every page. --replace-broken-text-layer sits in between: Docling checks each page's text layer and reads only the broken pages with full-page OCR.

docling convert contract.pdf --replace-broken-text-layer
docling convert contract.pdf --replace-broken-text-layer --ocr-engine tesseract --ocr-lang eng

• Off by default; works with every engine. In Python it is replace_broken_text_layer=True on any OCR options class, e.g. RapidOcrOptions(replace_broken_text_layer=True); on the CLI it is also available as --ocr-option replace_broken_text_layer=true.
• What counts as broken: control characters, � or private-use characters on the page or in many of its lines (any script), plus — for Latin text — accented letters standing in for another script (Îò÷¸ò for Russian) and words with too few vowels. One bad cell on an otherwise good page does not trigger a replacement.
• What it cannot detect: text in the right alphabet but with wrong or shuffled letters (Cartifecita). Use --ocr-mode full_page for those files.
• A replaced page keeps its low parse_score in the confidence report, because that score describes the PDF text layer. Pick an engine and --ocr-lang that can read the document's language.

Engine settings worth knowing#

List every key for an engine with docling options ocr ENGINE, then pass it with --ocr-option KEY=VALUE (repeatable).

docling convert scan.pdf --ocr-engine rapidocr --ocr-option backend=torch --ocr-option scale=2
docling convert scan.pdf --ocr-engine tesseract --ocr-lang deu,eng --ocr-option psm=6
docling convert scan.pdf --ocr-engine easyocr --ocr-lang iso:fr --ocr-option confidence_threshold=0.3
docling convert sideways.pdf --ocr-engine rapidocr --ocr-option backend=torch --ocr-option detect_orientation=true

Python#

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

opts = PdfPipelineOptions()
opts.do_ocr = True
opts.ocr_options = RapidOcrOptions(lang=["iso:ja"], backend="torch", mode=OcrMode.FULL_PAGE)

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

Option classes: OcrAutoOptions, RapidOcrOptions, EasyOcrOptions, TesseractCliOcrOptions (engine tesseract), TesseractOcrOptions (tesserocr), OcrMacOptions, NemotronOcrOptions, KserveV2OcrOptions.

Engine head-to-head on a scan#

Same scanned document (the first four pages of the Docling paper rasterised at 150 DPI with slight blur and skew), same standard pipeline, only the OCR engine changed. Each engine got one warm-up and three timed conversions on a 4-vCPU machine without a GPU, with Docling 2.148.0 on 6 Nov 2026.

• Tesseract was both fastest and most accurate here (5.5 s/page, 96.1% of words) — on clean, English, typeset pages it is hard to beat. It needs the system binary and language packs.
• RapidOCR on onnxruntime is about twice as fast as the default PyTorch backend (7.0 vs 15.4 s/page) with identical output. Installing docling[rapidocr] is the cheapest speed-up for a pure-Python setup — and auto picks it automatically once onnxruntime is present.
• EasyOCR was the slowest on CPU (29 s/page). With Docling's default confidence threshold (0.5) it kept 85.1% of the words; lowering it to 0.1 (--ocr-option confidence_threshold=0.1) raised that to 94.4%. Its results also depend strongly on the image: on the scan copy we used for the 27 October run, the same default threshold kept only 12.3%.

Frequently asked questions

Sources

• Docling source: OCR engines (docling/models/stages/ocr)
• Captured: docling options ocr <engine> output, Docling 2.148.0
• RapidOCR on PyPI
• EasyOCR on PyPI
• Tesseract OCR