PDF Pipeline Configuration#

PdfPipelineOptions is the primary configuration class for Docling's standard PDF conversion pipeline. It inherits from PaginatedPipelineOptions → ConvertPipelineOptions → PipelineOptions and controls text extraction strategy, OCR behavior, image resolution, and model enablement. 1

The class is defined in docling/datamodel/pipeline_options.py and is passed to DocumentConverter via PdfFormatOption(pipeline_options=...). 2

Key Parameters#

force_backend_text (default: False)#

When True, bypasses the layout model's text detection and uses the PDF backend's embedded text directly. 3 Useful for PDFs with reliable programmatic text layers. Note: VlmPipelineOptions has its own force_backend_text field with the same semantics, redirecting away from VLM text predictions to native backend text. 4

images_scale (default: 1.0)#

Scaling factor applied when rasterizing page images and picture images. Higher values produce higher-resolution images at the cost of memory and processing time. The CLI defaults to 2.0; values above 2.0 may cause bugs. 5 The field is defined on PaginatedPipelineOptions and overridden/re-declared on PdfPipelineOptions. 6

do_ocr (default: True)#

Enables OCR for bitmap regions detected on each page. When False, no OCR engine runs. Setting do_ocr=True with no further options uses OcrAutoOptions — automatic engine selection based on the runtime environment. 7 8

ocr_options (default: OcrAutoOptions())#

Selects and configures the OCR engine. All engine classes (OcrOptions) share two fields that directly control OCR strategy:

• force_full_page_ocr (default: False) — When True, OCR runs on the entire page regardless of whether a text layer exists, replacing programmatic cells with OCR output. 9 When active, BaseOcrModel.post_process_cells() filters out all non-OCR word and char cells so that stale programmatic cells don't corrupt downstream components such as the table structure model. 10

• bitmap_area_threshold (default: 0.05) — Minimum fraction of the page area a bitmap must cover before OCR is applied to it. Bitmaps covering less than 5% of the page are skipped entirely. 11

OCR Decision Logic (get_ocr_rects)#

BaseOcrModel.get_ocr_rects() implements the three-way dispatch:

1. force_full_page_ocr=True or bitmap coverage > 75% → Return a single rectangle covering the entire page.
2. Bitmap coverage > bitmap_area_threshold (but ≤ 75%) → Return individual merged bitmap rectangles.
3. Bitmap coverage ≤ bitmap_area_threshold → Return nothing; no OCR is run.

Bitmap regions are dilated by a 20×20 kernel to merge nearby rectangles before coverage is measured. 12

OCR Engine Options Summary#

All engine option classes inherit force_full_page_ocr and bitmap_area_threshold from OcrOptions. 13

14 15

Runtime Option Overrides#

Only do_* boolean flags (e.g., do_ocr, do_table_structure, do_code_enrichment) can be overridden at conversion time, and only from True → False. All other options — including images_scale, force_backend_text, and ocr_options — must match what was set at pipeline initialization. Attempting to enable a disabled flag or change other fields raises an error. 16

Common Pitfalls#

• Scanned PDFs with force_full_page_ocr=True: The layout model classifies full-page scans as PictureItem. OCR text is stored as children of those picture nodes. To export it, call export_to_markdown(traverse_pictures=True) or export_to_text(traverse_pictures=True). Without this flag, exports return empty results. 16

• Native PDF appearing as <!-- image -->: If a native PDF outputs only image placeholders, the layout model may be classifying text blocks as figures (e.g., due to vector graphics or unusual fonts). Setting force_full_page_ocr=True works around the symptom but replaces native text with OCR reconstruction. See issue #3002 for diagnostics and tradeoffs. 17

• images_scale > 2.0: Known to cause bugs. 5

• RapidOCR on read-only filesystems (e.g., Databricks): Use Tesseract or an alternative backend instead. 18

Key Source Files#