Docling Complete Technical Documentation

1. Overview & Architecture

Docling is an open-source document conversion and layout analysis engine created by IBM Research and maintained under LF AI & Data. Unlike naive plain-text extractors, Docling processes input documents through modular conversion pipelines that analyze page geometry, detect bounding boxes, parse headers and lists, reconstruct multi-column reading order, and infer complex tabular structures using neural vision models.

2. Installation & Environment Setup

Docling can be installed using standard Python package managers such as pip or uv. It supports Python 3.9 through Python 3.14 on Windows (64-bit), macOS, and Linux architectures.

Package Extras

Neural features and specialized OCR engines are provided as optional extras to minimize core installation weight:

3. Basic Quickstart Usage

Converting a document into structured Markdown requires only three lines of Python code using the primary DocumentConverter class.

from docling.document_converter import DocumentConverter

source = "https://arxiv.org/pdf/2408.09869" # Local path or URL
converter = DocumentConverter()
result = converter.convert(source)

# Export to Markdown
markdown_output = result.document.export_to_markdown()
print(markdown_output[:500])
              

4. The DoclingDocument Representation Model

The core output data model in Docling is the DoclingDocument schema. It maintains an object-oriented document tree containing structured elements such as sections, paragraphs, tables, code blocks, list items, and pictures with exact spatial coordinates (bounding boxes).

5. Processing Pipelines & Granite Docling VLM

Docling routes different file extensions to specialized processing pipelines:

• StandardPdfPipeline: Default engine for PDF and raster image layout analysis, TableFormer extraction, and OCR.
• VlmPipeline (Granite Docling): End-to-end vision-language model pipeline utilizing Granite Docling or SmolDocling presets for visual document parsing.
• AsrPipeline: Automatic Speech Recognition pipeline transcribing MP3, WAV, and audio tracks via Whisper.
• SimplePipeline: Lightweight parser for DOCX, PPTX, XLSX, HTML, and EPUB files.

5.1 Granite Docling VLM Model Setup

Granite Docling is IBM's official vision-language model preset built specifically for high-accuracy visual page layout understanding. To convert documents using Granite Docling in Python:

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

vlm_options = VlmPipelineOptions()
vlm_options.vlm_model = "granite_docling"  # Granite Docling VLM preset

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=vlm_options)}
)
result = converter.convert("complex_layout.pdf")
print(result.document.export_to_markdown())
              

6. OCR Engines, Multi-Language ONNX & Tuning

Architecture Note: Is Docling an OCR engine? Docling is not a standalone raw OCR engine like Tesseract, PaddleOCR, or EasyOCR. Instead, Docling is a high-level document understanding framework that wraps and orchestrates pluggable OCR engines under the hood. While raw OCR engines only extract text strings from cropped image pixels, Docling adds neural layout detection, multi-column reading order recovery, TableFormer matrix extraction, and exports structured Markdown and JSON for LLM RAG pipelines.

6.1 Disabling OCR for 10x Speed on Digital PDFs (`do_ocr = False`)

Digital PDFs generated directly by software (such as LaTeX, Microsoft Word, or Adobe InDesign) already contain native embedded text fonts and bounding boxes. For these files, running an OCR engine is redundant and significantly slows down processing. You can disable OCR to achieve a 5x to 10x throughput boost:

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

# 1. Create pipeline options and disable OCR
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = False  # Skip OCR: 10x faster for digital PDFs

# 2. Apply to converter
converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
result = converter.convert("digital_document.pdf")
print(result.document.export_to_markdown())
              

6.2 Configuring Multi-Language OCR (RapidOCR & Tesseract)

When processing scanned documents in multiple languages (such as Chinese, Japanese, Spanish, German, French, or Arabic), you can configure language codes directly in RapidOcrOptions or TesseractOcrOptions:

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

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True

# Option A: RapidOCR with ONNX runtime (Great for CJK & multilingual)
pipeline_options.ocr_options = RapidOcrOptions()

# Option B: Tesseract with explicit language codes
# pipeline_options.ocr_options = TesseractOcrOptions(lang=['en', 'de', 'es', 'fr', 'zh-CN', 'ja'])

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
result = converter.convert("scanned_multilingual.pdf")
              

7. Multi-Format Extraction (XLSX, PPTX, DOCX, CAD/Drawings & Audio)

Docling processes non-PDF formats through optimized format converters with the exact same unified Python API:

7.1 Microsoft Excel (.xlsx) Multi-Sheet Tabular Parsing

Docling parses Excel spreadsheets sheet-by-sheet, preserving merged headers, column hierarchies, and numerical formatting as Markdown/HTML tables:

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("financial_model.xlsx")

# Export complete workbook as structured Markdown
print(result.document.export_to_markdown())
              

7.2 PowerPoint (.pptx) Slide Deck Parsing

Extracts slide hierarchy, text shapes, embedded diagrams, and speaker notes:

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("presentation.pptx")
print(result.document.export_to_markdown())
              

7.3 Scanned CAD Diagrams & Engineering Drawings

Docling captures line-by-line annotations, drawing labels, and callouts from technical engineering schematics and architectural blueprints, outputting exact spatial bounding boxes via DoclingDocument.export_to_json().

8. RAG & Native Document Chunking (`HybridChunker`)

A major advantage of Docling over naive Markdown text splitters is its native chunking framework. Instead of splitting text blindly on token counts, Docling's HybridChunker operates directly on DoclingDocument nodes. Unlike naive text splitters, Docling HybridChunker natively preserves header context, table matrix structure, page numbers, and bounding box coordinates for precise RAG embedding and vector search.

from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker

# 1. Convert document
converter = DocumentConverter()
result = converter.convert("research_paper.pdf")

# 2. Initialize native HybridChunker
chunker = HybridChunker(max_tokens=512, merge_peers=True)
chunk_iter = chunker.chunk(result.document)

# 3. Iterate over structured chunks with metadata
for chunk in chunk_iter:
    print(f"Heading Path: {chunk.meta.headings}")
    print(f"Text Content: {chunk.text[:100]}...\n")
              

9. GPU Acceleration & High-Throughput Batch Tuning

Docling pipelines utilize PyTorch for neural layout analysis and OCR. To achieve maximum conversion throughput on large PDF datasets, configure AcceleratorOptions for NVIDIA CUDA or Apple Silicon MPS:

from docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions
from docling.datamodel.pipeline_options import ThreadedPdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

# 1. Enable CUDA / MPS GPU acceleration
accelerator_options = AcceleratorOptions(device=AcceleratorDevice.CUDA)

# 2. Increase batch size and thread concurrency for high throughput
pipeline_options = ThreadedPdfPipelineOptions(
    accelerator_options=accelerator_options,
    page_batch_size=8,      # Batch GPU inference across pages
    layout_batch_size=64,   # Layout detection batch size
    ocr_batch_size=64,      # OCR batch size
)

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

10. Framework Integrations (LangChain, LlamaIndex & Haystack)

Docling features native integrations with major Generative AI frameworks:

LangChain (`langchain-docling`)

from langchain_docling import DoclingLoader

loader = DoclingLoader(file_path="annual_report.pdf")
docs = loader.load()
print(f"Loaded {len(docs)} structured documents for LangChain RAG pipeline.")
              

LlamaIndex (`llama-index-readers-docling`)

from llama_index.readers.docling import DoclingReader

reader = DoclingReader()
documents = reader.load_data(file_path="financial_statement.pdf")
              

11. VLM Vision Model Catalog

Docling supports 15+ Vision-Language Model (VLM) presets for end-to-end visual page parsing:

12. FastAPI Server (`docling-serve`) & MCP Agent Server

To deploy Docling as an enterprise HTTP REST API service, run docling-serve (v1.21.0). It exposes async conversion endpoints and interactive OpenAPI Swagger docs at /docs.

12.1 Model Context Protocol (MCP) Integration

The docling-mcp server connects Docling directly into AI agent environments like Claude Desktop and LM Studio:

{
  "mcpServers": {
    "docling": {
      "command": "uvx",
      "args": [
        "--from=docling-mcp",
        "docling-mcp-server"
      ]
    }
  }
}
              

13. Enterprise Security, Privacy & Air-Gapped Deployment

Docling runs 100% on-premise and locally within your process or container. It does not send telemetry, document bytes, or embeddings to external cloud endpoints.

13.1 Air-Gapped Environment Pre-Caching Guide

In isolated or secure enterprise networks without internet access, pre-download model weights on a staging machine and transfer the cache:

# 1. In connected staging environment, pre-download all models
export DOCLING_CACHE_DIR="/opt/docling_models"
docling-tools models download --all

# 2. Transfer cache directory to air-gapped host, then run completely offline:
export HF_HUB_OFFLINE=1
export DOCLING_CACHE_DIR="/opt/docling_models"
docling document.pdf --to md
              

14. Developer Diagnostics & Common Error Fixes

Quick solutions to common developer runtime errors and migration issues:

15. Complete CLI Parameter Reference

Summary of all available flags for the docling command-line tool: