DocumentConverter Configuration#

DocumentConverter is Docling's main entry point for document conversion. Format-specific behavior is controlled by a format_options dictionary passed at construction, mapping each InputFormat enum value to a FormatOption instance. Formats not present in the dictionary receive default options automatically.

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=PdfPipelineOptions(...)),
        InputFormat.XLSX: ExcelFormatOption(backend_options=MsExcelBackendOptions(...)),
    }
)

Each FormatOption bundles three things 1:

If pipeline_options is not set, it is populated from pipeline_cls.get_default_options() at construction time. Pipelines are cached by a composite key of (pipeline_class, md5(pipeline_options)), so multiple formats sharing the same class and options reuse a single initialized pipeline 2.

Class Hierarchy#

FormatOption classes (docling/document_converter.py)#

Each supported format has a named FormatOption subclass pre-wired with the correct pipeline_cls and backend 3:

The base BaseFormatOption (in docling/datamodel/base_models.py) holds the pipeline_options and backend fields; FormatOption adds backend_options and the pipeline_cls field 4.

pipeline_options — docling/datamodel/pipeline_options.py#

The pipeline_options field accepts any PipelineOptions subclass. The hierarchy is:

PipelineOptions ← timeout, accelerator, artifacts_path
└── ConvertPipelineOptions ← picture classification/description, chart extraction
    └── PaginatedPipelineOptions ← images_scale, generate_page_images
        ├── PdfPipelineOptions ← OCR, table structure, layout, formula enrichment
        └── VlmPipelineOptions ← VLM-based holistic page understanding
AsrPipelineOptions ← speech recognition (audio)

Key PipelineOptions fields 5: document_timeout, accelerator_options, enable_remote_services, artifacts_path.

Key ConvertPipelineOptions additions 6: do_picture_classification, do_picture_description, picture_description_options, do_chart_extraction, chart_extraction_options.

Key PdfPipelineOptions additions 7: do_ocr, force_ocr, ocr_engine, do_table_structure, table_structure_options, do_code_enrichment, do_formula_enrichment, pdf_backend.

Runtime override constraint: Only do_* flags can be changed at conversion time (and only from True → False). All other options must be identical to those used at pipeline initialization. Attempting to enable a do_* flag or change non-flag fields raises an error 7.

backend_options — docling/datamodel/backend_options.py#

The backend_options field is typed as BackendOptions, a discriminated union keyed on kind. Not all FormatOption subclasses expose backend_options; only those with format-specific parsing configuration do:

Examples#

PDF with custom OCR and table extraction:

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

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = False
pipeline_options.do_table_structure = True

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    }
)

XLSX with sheet filtering:

from docling.datamodel.backend_options import MsExcelBackendOptions
from docling.document_converter import DocumentConverter, ExcelFormatOption
from docling.datamodel.base_models import InputFormat

converter = DocumentConverter(
    format_options={
        InputFormat.XLSX: ExcelFormatOption(
            backend_options=MsExcelBackendOptions(sheet_names=["Summary", "Q4"])
        )
    }
)

8

HTML with headless browser rendering:

from docling.datamodel.backend_options import HTMLBackendOptions
from docling.document_converter import DocumentConverter, HTMLFormatOption
from docling.datamodel.base_models import InputFormat

converter = DocumentConverter(
    format_options={
        InputFormat.HTML: HTMLFormatOption(
            backend_options=HTMLBackendOptions(render_page=True, fetch_images=True)
        )
    }
)

Key Source Files#