OCR Engine Configuration#

Docling's OCR subsystem is configured through two orthogonal mechanisms: ocr_options on PdfPipelineOptions selects and tunes the engine per-conversion, and DebugSettings (in settings.py) enables global debug visualization of OCR and adjacent pipeline stages.

Enabling OCR#

OCR is activated via PdfPipelineOptions:

from docling.datamodel.pipeline_options import PdfPipelineOptions, EasyOcrOptions

opts = PdfPipelineOptions()
opts.do_ocr = True # default: True
opts.ocr_options = EasyOcrOptions(lang=["en", "de"])

do_ocr=True (default) applies OCR to bitmap regions. Set force_full_page_ocr=True on any OcrOptions subclass to always OCR the entire page 1. bitmap_area_threshold (default 0.05) skips OCR on bitmaps smaller than 5% of the page area 2.

Available Engines#

All engine options inherit from OcrOptions and are set as PdfPipelineOptions.ocr_options. The default is OcrAutoOptions().

The deprecated OcrEngine enum is no longer the canonical list — use get_ocr_factory().registered_kind to enumerate all registered engines at runtime (including external plugins).

Auto-Selection Logic#

OcrAutoOptions triggers OcrAutoModel, which probes the environment in this order:

1. macOS → OcrMacModel
2. Linux → NemotronOcrModel
3. Fallback chain: RapidOCR (onnxruntime) → EasyOCR → RapidOCR (torch)

Because lang defaults to [] with OcrAutoOptions 3, language selection is deferred to the engine that gets chosen. Specify an explicit engine class to control languages.

Engine-Specific Options Reference#

EasyOcrOptions — key fields 4:

• lang: ISO 639-1 codes, default ["fr", "de", "es", "en"]
• use_gpu: None (auto-detect), True, or False
• confidence_threshold: 0.5 — filters low-confidence results
• model_storage_directory: override model cache path
• recog_network: "standard" or "craft"

TesseractCliOcrOptions / TesseractOcrOptions — key fields 5:

• lang: ISO 639-2 codes, default ["fra", "deu", "spa", "eng"]
• psm: Tesseract Page Segmentation Mode (0–13); None = Tesseract default
• path: override TESSDATA_PREFIX; CLI also exposes tesseract_cmd

RapidOcrOptions — key fields 6:

• backend: "onnxruntime" (default), "openvino", "paddle", "torch"
• text_score: detection confidence threshold (default 0.5)
• use_det, use_cls, use_rec: individually toggle detection/classification/recognition stages
• print_verbose: enable verbose logging from the RapidOCR engine
• rapidocr_params: dict pass-through for any other RapidOCR setting
• ⚠️ Known issue: read-only filesystems (e.g., Databricks) may cause failures; prefer Tesseract there 7

OcrMacOptions — key fields 8:

• lang: locale codes, default ["fr-FR", "de-DE", "es-ES", "en-US"]
• recognition: "accurate" (default) or "fast"
• framework: "vision" (Apple Vision framework)

NemotronOcrOptions — key fields 9:

• lang: "english" or "multilingual" (Nemotron OCR v2)
• merge_level: "word", "sentence" (default), or "paragraph" — granularity of output cells
• batch_size: number of image crops to process together (default 8)

KserveV2OcrOptions — key fields 10:

• url: host:port for gRPC, http(s)://host:port for HTTP
• transport: "grpc" (default) or "http"
• model_name: registered model name on the server (default "ocr")
• scale: image scale multiplier (default 2.0)
• See the KServe v2 notes in the knowledge base for authentication, TLS, and load-balancing details.

Debug Visualization#

DebugSettings in settings.py controls global debug image output. All flags default to False; images are written to debug_output_path (default: ./debug/).

Configure via environment variables (prefix DOCLING_, nested delimiter _) 11 or programmatically:

from docling.datamodel.settings import settings, DebugSettings

settings.debug = DebugSettings(
    visualize_ocr=True,
    visualize_layout=True,
    debug_output_path="/tmp/docling_debug",
)

Use the scoped() context manager to temporarily override settings and guarantee restoration:

from docling.datamodel.settings import scoped, DebugSettings

with scoped(debug=DebugSettings(visualize_layout=True)):
    result = converter.convert(source)

Key Source Files#