Docling Pipeline Configuration#

All pipeline configuration lives in docling/datamodel/pipeline_options.py — a Pydantic model hierarchy that controls OCR engine selection, table extraction, enrichment models, and more. The CLI (docling/cli/main.py) maps docling convert flags directly to fields on these classes.

Three concrete pipeline option classes cover different input types:

Inheritance Hierarchy#

PipelineOptions # document_timeout, accelerator_options, enable_remote_services, artifacts_path
└── ConvertPipelineOptions # do_picture_classification, do_picture_description, do_chart_extraction
    └── PaginatedPipelineOptions # images_scale, generate_page_images, generate_picture_images
        ├── PdfPipelineOptions # do_ocr, do_table_structure, do_code_enrichment, do_formula_enrichment
        └── VlmPipelineOptions # vlm_options, force_backend_text
AsrPipelineOptions # asr_options (directly extends PipelineOptions)

1 2

Key fields by layer:

• PipelineOptions 3: document_timeout, accelerator_options, enable_remote_services (default False), allow_external_plugins (default False), artifacts_path.
• ConvertPipelineOptions 4: do_picture_classification, do_picture_description, picture_description_options, do_chart_extraction, chart_extraction_options. All picture/chart flags default to False.
• PaginatedPipelineOptions 5: images_scale (default 1.0; CLI sets 2.0 when image export is requested), generate_page_images (default False), generate_picture_images (default False).
• VlmPipelineOptions 6: inherits all of the above; overrides generate_page_images=True (VLM requires rendered pages); adds vlm_options (default preset: "granite_docling"), force_backend_text (default False).
• AsrPipelineOptions 7: asr_options (default WHISPER_TINY). Does not extend ConvertPipelineOptions.

CLI → PipelineOptions Mapping#

The convert command (cli/main.py:700) constructs a PipelineOptions subclass based on --pipeline and wires each flag to the corresponding field 8.

Standard pipeline (--pipeline standard → PdfPipelineOptions)#

VLM pipeline (--pipeline vlm → VlmPipelineOptions)#

--vlm-model <preset> selects the VLM via VlmConvertOptions.from_preset(vlm_model) 9. The default preset is "granite_docling". Available presets are enumerated at import time from VlmConvertOptions.list_preset_ids() 10.

ASR pipeline (audio inputs → AsrPipelineOptions)#

--asr-model <type> maps through _resolve_asr_options() 11 to an InlineAsrOptions preset (e.g., WHISPER_TURBO). The AsrPipelineOptions instance is always built regardless of pipeline mode and attached to InputFormat.AUDIO 12.

OCR Engine Selection#

PdfPipelineOptions.ocr_options defaults to OcrAutoOptions() — kind="auto". At runtime, OcrAutoModel probes the environment in order:

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

Because OcrAutoOptions.lang defaults to [] 13, language selection is deferred to whichever engine is chosen. To control languages, specify an explicit engine class.

All engine option classes inherit force_full_page_ocr (default False) and bitmap_area_threshold (default 0.05) from OcrOptions.

Available engines#

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

The CLI --ocr-engine flag accepts the kind string (e.g., --ocr-engine easyocr); it passes the value to ocr_factory.create_options(kind=ocr_engine, ...) 15.

Enrichment Feature Flags#

All enrichment models are disabled by default because they require additional model inference 16. The two exceptions are do_ocr and do_table_structure, which default to True on PdfPipelineOptions.

Code/formula enrichment options#

PdfPipelineOptions.code_formula_options 24 is a CodeFormulaVlmOptions instance. Two presets are registered 25:

• "codeformulav2" — default
• "granite_docling" — IBM Granite-Docling-258M

Switch presets via CodeFormulaVlmOptions.from_preset("granite_docling").

Runtime override constraint#

Only do_* boolean flags may be overridden at conversion time, and only in the True → False direction. Changing any other field (including ocr_options or images_scale) or re-enabling a disabled flag raises an error 26.

Key Source Files#