Docling Administrator & Developer Guide

Docling is an open-source Python framework developed by IBM Research for converting documents from 17 input formats into 8 output formats. It combines AI-powered OCR, layout analysis, table structure recognition, and vision-language models to produce structured document representations. This guide covers the architecture, configuration, deployment, and internals that administrators, operators, and contributing developers need.

1. Architecture Overview

1.1 High-Level Component Diagram

                         ┌─────────────────────────────────────────────────┐
                         │              DocumentConverter                  │
                         │   (docling/document_converter.py)               │
                         │                                                 │
                         │  ┌──────────────┐   ┌───────────────────────┐   │
  Sources ──────────────►│  │  FormatOption │   │     InputDocument     │   │
  (file/URL/stream)      │  │  (per-format) │   │  (source + metadata)  │   │
                         │  └──────┬───────┘   └───────────┬───────────┘   │
                         │         │                       │               │
                         │         ▼                       ▼               │
                         │  ┌──────────────┐   ┌───────────────────────┐   │
                         │  │   Backend    │   │      Pipeline         │   │
                         │  │  (parsing)   │──►│    (processing)       │   │
                         │  └──────────────┘   └───────────┬───────────┘   │
                         │                                 │               │
                         │                                 ▼               │
                         │                     ┌───────────────────────┐   │
                         │                     │   ConversionResult    │   │
                         │                     │   (DoclingDocument)   │   │
                         │                     └───────────┬───────────┘   │
                         └─────────────────────────────────┼───────────────┘
                                                           │
                                                           ▼
                                              ┌───────────────────────┐
                                              │   Export / Save As    │
                                              │  MD / JSON / YAML /   │
                                              │  HTML / DocTags / etc │
                                              └───────────────────────┘

Pipeline Detail (StandardPdfPipeline):

  ┌──────────┐   ┌────────┐   ┌─────┐   ┌───────────┐   ┌─────────┐   ┌──────────┐
  │Preprocess│──►│ Layout │──►│ OCR │──►│Table Struct│──►│Read Ord.│──►│Page Assem│
  └──────────┘   └────────┘   └─────┘   └───────────┘   └─────────┘   └──────────┘
                                                                            │
                                                                            ▼
                                                              ┌─────────────────────┐
                                                              │ Optional Enrichments │
                                                              │ Code │ Formula │ Pic │
                                                              │ Chart│ PicClass│ Desc│
                                                              └─────────────────────┘

Note

Docling itself is a library and CLI tool, not a web server. The HTTP/REST serving layer lives in the separate docling-serve project. This guide covers the core conversion framework only.

1.2 Component Inventory

1.3 Technology Stack

1.4 Ecosystem Context

Docling is part of a family of packages:

1.5 Data Flow

1. Input: User provides a source — local file path, HTTP(S) URL, or byte stream — along with optional per-format configuration.
2. Format detection: DocumentConverter inspects the file extension and MIME type to select the matching FormatOption, which pairs a Backend with a Pipeline and format-specific Options.
3. Backend parsing: The chosen backend (e.g., DoclingParseDocumentBackend for PDF) opens the file and exposes pages or document structure.
4. Pipeline processing: For paginated formats (PDF, images), the StandardPdfPipeline runs a multi-stage sequence: page preprocessing, layout analysis, OCR, table structure recognition, reading order determination, and page assembly. For declarative formats (DOCX, HTML, Markdown, CSV), the SimplePipeline delegates directly to the backend's convert() method.
5. Enrichment (optional): After assembly, optional enrichment models run: code detection, formula recognition, picture description, picture classification, chart extraction.
6. Output: A ConversionResult wraps the DoclingDocument (from docling-core), which can be exported to Markdown, JSON, YAML, HTML, DocTags, or other formats.

1.6 Pipeline Descriptions

StandardPdfPipeline — The primary pipeline for PDF and image documents. Runs six sequential stages (each parallelized across pages via threaded pipeline stages), then optional enrichments. This is the most resource-intensive path and where GPU acceleration matters most.

VlmPipeline — An alternative for PDF/image processing that sends page images to a vision-language model (e.g., Granite Vision, SmolDocling) for direct conversion. Trades the multi-model pipeline for a single VLM call per page. Supports local inference (Transformers, vLLM, MLX) or remote API.

SimplePipeline — Handles declarative/structured formats (DOCX, HTML, Markdown, LaTeX, CSV, XLSX, PPTX, AsciiDoc, WebVTT, XBRL, JATS XML, USPTO XML). Calls the backend's convert() method directly; no ML models involved.

AsrPipeline — Automatic speech recognition for audio/video files. Uses OpenAI Whisper models (standard or MLX variant on Apple Silicon).

ExtractionVlmPipeline — Experimental. Uses a VLM to extract structured information from documents according to a user-defined schema.

2. System Requirements

2.1 Python Version

Python 3.10 or higher is required. The codebase uses modern type hints (X | Y union syntax, TypeVar with bounds) that require 3.10+.

2.2 Operating System Support

2.3 Hardware Requirements

CPU-only (minimum):

• 4+ cores recommended (controlled by DOCLING_NUM_THREADS, default 4)
• 8 GB RAM minimum; 16 GB recommended for large PDFs
• SSD storage for model cache (models download to ~/.cache/huggingface/)

GPU-accelerated (recommended for production):

• NVIDIA GPU with CUDA support (PyTorch CUDA backend)
• Apple Silicon MPS (Metal Performance Shaders) for macOS
• GPU memory: 4 GB minimum for layout + table models; 8+ GB for VLM models
• Flash Attention 2 support optional (set DOCLING_CUDA_USE_FLASH_ATTENTION2=true)

Tip

Docling auto-detects the best available device (CUDA → MPS → CPU). Override with DOCLING_DEVICE=cpu to force CPU-only mode, useful for debugging or resource-constrained environments.

2.4 Dependency Groups

Docling uses optional dependency groups (extras) to keep the base install lean:

Install example:

pip install "docling[vlm,rapidocr]"

2.5 Model Downloads

On first use, ML models download automatically from Hugging Face Hub to ~/.cache/huggingface/hub/. Key models:

Pre-download models for air-gapped or Docker deployments:

# Uses the docling CLI to pre-download all default models
docling models download

3. Configuration Reference

3.1 Environment Variables

3.2 Application Settings (AppSettings)

Defined in docling/datamodel/settings.py. These are Pydantic BaseSettings fields with the DOCLING_ environment variable prefix. Access at runtime via docling_settings().

Performance Settings (perf)

Debug Settings (debug)

Limit Settings (limits)

Batch Settings

3.3 Pipeline Options

3.3.1 PdfPipelineOptions

The primary configuration object for StandardPdfPipeline. Pass as part of FormatOption when configuring DocumentConverter.

Example configuration:

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    TableStructureOptions,
    TableFormerMode,
)

pipeline_options = PdfPipelineOptions(
    do_ocr=True,
    do_table_structure=True,
    table_structure_options=TableStructureOptions(
        mode=TableFormerMode.ACCURATE,
    ),
    do_picture_description=True,
    generate_page_images=True,
    images_scale=2.0,
    document_timeout=300.0,
)

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

3.3.2 VlmPipelineOptions

Configuration for the VlmPipeline (VLM-based conversion).

3.3.3 AsrPipelineOptions

Configuration for the AsrPipeline (audio/video transcription).

3.3.4 VlmExtractionPipelineOptions

Configuration for ExtractionVlmPipeline (experimental structured extraction).

3.4 OCR Options

All OCR options inherit from OcrOptions. The OcrAutoOptions default automatically selects the best available engine.

OcrAutoOptions (default)

EasyOcrOptions

TesseractCliOcrOptions

TesseractOcrOptions (tesserocr bindings)

RapidOcrOptions

OcrMacOptions (macOS only)

KserveV2OcrOptions (remote)

Important

KserveV2OcrOptions requires enable_remote_services=True in the pipeline options. Attempting to use it without this flag raises OperationNotAllowed.

3.5 VLM Options

VLM (Vision Language Model) options control how page images are converted to structured text.

VlmConvertOptions

InlineVlmOptions (local inference)

ApiVlmOptions (remote API)

3.6 Backend Options

HTMLBackendOptions

MarkdownBackendOptions

PdfBackendOptions

MsExcelBackendOptions

LatexBackendOptions

XBRLBackendOptions

4. Deployment & Scaling

4.1 Installation Methods

pip install (recommended for most users)

# Base install (PDF, DOCX, HTML, Markdown, CSV, PPTX, XLSX support)
pip install docling

# With specific OCR engine
pip install "docling[easyocr]"
pip install "docling[rapidocr]"
pip install "docling[tesserocr]"

# With VLM support
pip install "docling[vlm]"

# With audio/video support
pip install "docling[asr]"

# With HTML rendering (Playwright)
pip install "docling[htmlrender]"

# Multiple extras
pip install "docling[vlm,rapidocr,asr]"

After installing extras that require Playwright:

playwright install chromium

Docker

A Dockerfile is provided at the repository root. Build and run:

# Build
docker build -t docling:latest .

# Run with GPU support (NVIDIA)
docker run --gpus all -v /path/to/docs:/data docling:latest \
    docling convert /data/input.pdf --output /data/output/

# Run CPU-only
docker run -v /path/to/docs:/data docling:latest \
    docling convert /data/input.pdf --output /data/output/

# Pre-download models into a persistent volume
docker run -v docling-models:/root/.cache/huggingface docling:latest \
    docling models download

Tip

Mount the Hugging Face cache directory (~/.cache/huggingface) as a Docker volume to avoid re-downloading models on every container restart: -v docling-models:/root/.cache/huggingface.

Development install

git clone https://github.com/docling-project/docling.git
cd docling

# Using uv (recommended, matches CI)
uv sync --all-extras

# Or pip in editable mode
pip install -e ".[vlm,rapidocr,asr,htmlrender,tesserocr]"

# Install pre-commit hooks
pre-commit install

4.2 Model Management

Pre-downloading models

For production deployments, air-gapped environments, or Docker images, pre-download all models:

# Download all default models
docling models download

# Models are cached in HF_HOME (~/.cache/huggingface/hub/ by default)

Custom model paths

Set HF_HOME to control where models are stored:

export HF_HOME=/opt/models/huggingface
docling models download

Model artifacts path

When models fail to load, the error "The value of self.artifacts_path=... is not valid" indicates the cached model directory is missing or corrupted. Delete the cache entry and re-download:

rm -rf ~/.cache/huggingface/hub/models--ds4sd--docling-models
docling models download

4.3 Service Client Setup (docling-serve)

The DoclingServiceClient connects to a running docling-serve instance. This is relevant for architectures where conversion is offloaded to a dedicated server.

from docling.service_client import DoclingServiceClient

client = DoclingServiceClient(
    url="http://docling-serve:5001",
    api_key="your-api-key",  # optional
)

# Synchronous-style conversion (blocks until complete)
result = await client.convert(source="https://example.com/paper.pdf")

# Batch conversion
results = await client.convert_all(sources=[
    "paper1.pdf", "paper2.pdf", "paper3.pdf"
])

# Async submission with polling
task = await client.submit(source="large-document.pdf")
watcher = PollingWatcher(client, task.task_id, poll_interval=5.0)
result = await watcher.wait()

The client raises typed exceptions:

4.4 Scaling Strategies

Vertical scaling — increase resources on a single machine:

• Add GPU(s) for model inference
• Increase DOCLING_NUM_THREADS for CPU parallelism
• Increase perf.page_batch_size for larger batches

Horizontal scaling — run multiple instances:

• Deploy multiple docling-serve instances behind a load balancer
• Use the DoclingServiceClient from application code
• Each instance handles its own model loading and inference

Batch processing — for offline/bulk workloads:

• Use DocumentConverter.convert_all() for multi-document batches
• Control concurrency via batch_concurrency setting
• Set document_timeout to prevent single documents from blocking the batch

5. Operations

5.1 Batch Processing

from docling.document_converter import DocumentConverter, DocumentStream
from pathlib import Path

converter = DocumentConverter()

# Convert multiple files
sources = [
    Path("doc1.pdf"),
    Path("doc2.docx"),
    "https://example.com/paper.pdf",
]

results = converter.convert_all(sources)

for result in results:
    if result.status == ConversionStatus.SUCCESS:
        result.document.save_as_markdown(Path(f"output/{result.input.file.stem}.md"))
    else:
        print(f"Failed: {result.input.file} — {result.errors}")

Warning

When processing untrusted documents in batch, always set document_timeout to prevent a single malformed file from stalling the entire batch. A timeout of 300-600 seconds is reasonable for most documents; very large PDFs (1000+ pages) may need more.

5.2 CLI Operations

The CLI provides 11 commands. Key operational commands:

# Convert a single file
docling convert input.pdf --output ./output/

# Convert with specific format options
docling convert input.pdf --ocr --table-structure --output ./output/

# Convert with VLM pipeline
docling convert input.pdf --pipeline vlm --output ./output/

# Batch convert a directory
docling convert ./input_dir/ --output ./output/

# Download models
docling models download

# List supported formats
docling formats list

Use --allow-external-plugins to enable third-party model plugins:

docling convert input.pdf --allow-external-plugins --output ./output/

5.3 Monitoring and Profiling

Enable pipeline profiling to identify bottlenecks:

from docling.datamodel.settings import docling_settings

settings = docling_settings()
settings.debug.profile_pipeline_timings = True

Or via environment variable:

export DOCLING_DEBUG__PROFILE_PIPELINE_TIMINGS=true

This logs per-stage timing for each page, producing output like:

Stage preprocess: 0.12s
Stage layout: 1.45s
Stage ocr: 2.31s
Stage table_structure: 0.89s
Stage reading_order: 0.05s
Stage page_assembly: 0.03s

Note

Enable debug visualization (debug.visualize_layout, debug.visualize_tables, etc.) to generate annotated page images. These are written alongside the output and are invaluable for diagnosing layout or table recognition issues.

5.4 Error Handling

Docling uses a structured error model. Key error scenarios and their handling:

For batch operations, check ConversionResult.status per document — Docling does not abort the batch on individual failures.

5.5 Timeout Configuration

Timeouts operate at two levels:

1. Document-level timeout (document_timeout in pipeline options): Limits total processing time for a single document. Set in seconds. None means unlimited.

2. Backend-level timeout (parse_timeout in LatexBackendOptions): Limits parsing time for specific backends. The LaTeX backend defaults to 30 seconds to guard against pathological inputs.

For production batch processing, recommended settings:

pipeline_options = PdfPipelineOptions(
    document_timeout=600.0,       # 10 minutes per document
    do_ocr=True,
    do_table_structure=True,
)

5.6 Logging

Docling uses Python's standard logging module. Configure log levels:

import logging
logging.getLogger("docling").setLevel(logging.DEBUG)

Key loggers:

6. Performance

6.1 GPU Acceleration

Docling's ML models (layout analysis, table structure, OCR, VLM) benefit significantly from GPU acceleration.

Device selection priority (when DOCLING_DEVICE=auto):

1. CUDA (NVIDIA GPU) — if torch.cuda.is_available()
2. MPS (Apple Silicon) — if torch.backends.mps.is_available()
3. CPU — fallback

Force a specific device:

export DOCLING_DEVICE=cuda    # NVIDIA GPU
export DOCLING_DEVICE=mps     # Apple Silicon
export DOCLING_DEVICE=cpu     # CPU only

6.2 Flash Attention 2

For CUDA devices with compatible hardware (Ampere or newer), Flash Attention 2 reduces memory usage and improves throughput for attention-heavy models (VLM, layout analysis):

pip install flash-attn
export DOCLING_CUDA_USE_FLASH_ATTENTION2=true

Important

Flash Attention 2 requires CUDA compute capability 8.0+ (A100, RTX 3090/4090, H100). It will silently fall back to standard attention on incompatible hardware without error.

6.3 Threading and Parallelism

Threaded pipeline — StandardPdfPipeline uses ThreadedPipelineStage for parallel page processing. Each stage (preprocess, layout, OCR, table structure, reading order, assembly) runs as a bounded producer-consumer queue, allowing pipeline-level parallelism across pages.

The ThreadedQueue implementation uses a bounded buffer to prevent memory exhaustion when processing documents with thousands of pages.

CPU thread control:

# Control inference threads (ONNX Runtime, PyTorch)
export DOCLING_NUM_THREADS=8

# Alternative (OpenMP)
export OMP_NUM_THREADS=8

Batch size tuning:

Increase perf.page_batch_size to process more pages per inference batch. This improves GPU utilization but increases peak memory:

from docling.datamodel.settings import docling_settings

settings = docling_settings()
settings.perf.page_batch_size = 8  # Default varies; tune based on GPU memory

6.4 VLM Inference Engines

For VLM-based conversion, three local inference engines are available:

vLLM typically provides the best throughput for batch processing on NVIDIA GPUs. MLX is optimal for Apple Silicon. Transformers is the most compatible fallback.

6.5 Performance Optimization Checklist

1. Use GPU if available (DOCLING_DEVICE=cuda or auto)
2. Enable Flash Attention 2 on compatible CUDA hardware
3. Tune DOCLING_NUM_THREADS to match available cores (avoid over-subscription)
4. Increase perf.page_batch_size for GPU workloads (monitor memory)
5. Disable unnecessary enrichments (do_code_enrichment, do_formula_enrichment, etc.) if not needed
6. Use TableFormerMode.FAST instead of ACCURATE when precision is less critical
7. Set document_timeout to prevent runaway processing
8. For VLM pipeline, prefer vLLM on NVIDIA GPUs for best throughput
9. Pre-download models to avoid first-run latency
10. Use limits.max_num_pages to cap processing for very large documents

6.6 Known Performance Issues

• Issue #3182: A 2x performance regression was reported in version 2.81.0. Check release notes for fixes in later versions.
• Issue #3201: SIGABRT on Python 3.12 in Databricks Serverless environments. Likely related to thread/process model incompatibility.
• Issue #3303: ChartExtractionModel crash with transformers>=5.x. Pin transformers version if using chart extraction.

7. Security

7.1 Input Validation

Docling validates inputs at multiple levels:

• Format detection: Files must match a recognized format (extension + MIME type). Unrecognized formats raise ConversionError.
• File size limits: Configurable via limits.max_file_size. Enforce this in production to prevent denial-of-service via oversized files.
• Page limits: Configurable via limits.max_num_pages. Prevents resource exhaustion from extremely large documents.
• Parse timeouts: Backend-level timeouts (e.g., LatexBackendOptions.parse_timeout = 30s) prevent pathological inputs from consuming unbounded CPU.

7.2 Password-Protected PDFs

Docling supports opening encrypted PDFs via PdfBackendOptions:

from docling.datamodel.pipeline_options import PdfBackendOptions

backend_options = PdfBackendOptions(password="secret123")

Caution

PDF passwords are passed in plaintext through the options object. Do not log pipeline options in production environments where password-protected documents are processed. Ensure options objects containing passwords are not serialized to disk or transmitted.

7.3 Remote Fetch Controls

Several features involve fetching remote resources:

Warning

Enabling fetch_images=True or render_page=True on untrusted HTML/Markdown inputs allows the process to make outbound HTTP requests to arbitrary URLs. In sandboxed or security-sensitive environments, keep these disabled or restrict network access at the OS/container level.

7.4 Remote Services Flag

The enable_remote_services flag in pipeline options is a global gate for any operation that contacts an external service during conversion. This includes:

• KserveV2OcrOptions (remote OCR)
• ApiVlmOptions (remote VLM API)
• Any future remote model integration

This flag is False by default. Attempting to use a remote service without it raises OperationNotAllowed.

7.5 Plugin Trust Model

The factory-based plugin system allows third-party packages to register custom OCR, layout, or table structure implementations via Python entry points.

allow_external_plugins=False (default): Only built-in model implementations are loaded. Third-party entry points are ignored.

allow_external_plugins=True: The BaseFactory.load_from_plugins() method discovers and loads external implementations. This executes code from third-party packages at import time.

In production, only enable external plugins when you trust all installed packages. The CLI equivalent is --allow-external-plugins.

7.6 Dependency Supply Chain

Key security-sensitive dependencies:

8. Developer Internals

8.1 Repository Structure

docling/
├── __init__.py               # Package init, version
├── document_converter.py     # Core orchestrator (DocumentConverter)
├── chunking.py               # Document chunking for RAG
├── exceptions.py             # Custom exception hierarchy
├── backend/                  # Format-specific backends (20+ files)
│   ├── abstract_backend.py   # AbstractDocumentBackend (ABC)
│   ├── pdf_backend.py        # PdfDocumentBackend
│   ├── docling_parse_backend.py  # DoclingParseDocumentBackend
│   ├── pypdfium_backend.py   # PyPdfiumDocumentBackend
│   ├── msword_backend.py     # MsWordDocumentBackend
│   ├── mspowerpoint_backend.py
│   ├── msexcel_backend.py
│   ├── html_backend.py
│   ├── md_backend.py
│   ├── csv_backend.py
│   ├── latex_backend.py
│   ├── asciidoc_backend.py
│   ├── image_backend.py
│   ├── webvtt_backend.py
│   ├── mets_gbs_backend.py
│   ├── jats_backend.py
│   ├── patent_uspto_backend.py
│   ├── xbrl_backend.py
│   └── noop_backend.py       # Pass-through backend
├── datamodel/                # Pydantic models (20 files)
│   ├── settings.py           # AppSettings (env-based config)
│   ├── pipeline_options.py   # All pipeline/backend/model options
│   ├── document.py           # InputDocument, ConversionResult
│   └── ...
├── pipeline/                 # Processing pipelines (9 files)
│   ├── base_pipeline.py      # BasePipeline (ABC)
│   ├── convert_pipeline.py   # ConvertPipeline base
│   ├── standard_pdf_pipeline.py  # StandardPdfPipeline
│   ├── vlm_pipeline.py       # VlmPipeline
│   ├── simple_pipeline.py    # SimplePipeline
│   ├── asr_pipeline.py       # AsrPipeline
│   ├── extraction_vlm_pipeline.py
│   ├── threaded_pipeline.py  # ThreadedPipelineStage, ThreadedQueue
│   └── ...
├── models/                   # ML model wrappers (5 base + 6 factories + 6 engines)
│   ├── base_model.py         # BasePageModel (ABC)
│   ├── base_ocr_model.py     # BaseOcrModel
│   ├── layout_model.py
│   ├── table_structure_model.py
│   ├── vlm_convert_model.py
│   ├── factories/            # Factory pattern implementations
│   │   ├── base_factory.py   # BaseFactory[A] generic
│   │   ├── ocr_factory.py
│   │   ├── layout_factory.py
│   │   ├── table_structure_factory.py
│   │   └── picture_description_factory.py
│   └── inference_engines/    # VLM inference backends
│       ├── transformers_engine.py
│       ├── vllm_engine.py
│       ├── mlx_engine.py
│       ├── api_engine.py
│       └── ...
├── service_client/           # Remote service SDK (6 files)
│   ├── client.py             # DoclingServiceClient
│   ├── watchers.py           # PollingWatcher, WebSocketWatcher
│   └── exceptions.py         # Service exceptions
├── cli/                      # CLI interface (3 files)
│   ├── main.py               # Entry point, command registration
│   └── ...
└── utils/                    # Utilities (13 files)
    ├── profiling.py          # Pipeline timing profiler
    ├── accelerator_utils.py  # Device detection (CUDA/MPS/CPU)
    ├── locks.py              # Thread-safe resource locking
    └── ...

8.2 Module Reference

docling/document_converter.py (37K chars)

The central orchestrator. DocumentConverter accepts format options (a dict mapping InputFormat to FormatOption), creates backends and pipelines per format, and runs conversion. Key methods:

• convert(source) — Convert a single document. Returns ConversionResult.
• convert_all(sources) — Convert multiple documents. Returns iterator of ConversionResult.
• _get_pipeline(format_option) — Instantiate or retrieve cached pipeline for a format option.
• _determine_backend(source) — Select the backend class based on source format.

docling/backend/ (420K chars, 19 files)

Each backend implements AbstractDocumentBackend (or its subclasses PaginatedDocumentBackend / DeclarativeDocumentBackend). Key methods:

• is_valid(source) — Class method. Check if the backend can handle this source.
• page_count() — Return page count (paginated backends only).
• load_page(page_no) — Load a specific page (paginated backends only).
• convert() — Convert the entire document (declarative backends).

The DoclingParseDocumentBackend is the default PDF backend, using the C++-accelerated docling-parse library for text extraction and cell detection. PyPdfiumDocumentBackend is the fallback using pypdfium2.

docling/datamodel/ (252K chars, 20 files)

All Pydantic models live here. The pipeline_options.py file is the largest and most important — it defines every configurable option for pipelines, backends, OCR engines, VLM models, and table structure.

docling/pipeline/ (118K chars, 9 files)

Pipeline implementations. StandardPdfPipeline is the most complex, with six sequential stages plus optional enrichments. Each stage implements BasePageModel and is wrapped in a ThreadedPipelineStage for parallel execution.

The ThreadedPipelineStage creates a bounded producer-consumer queue (ThreadedQueue) where pages flow through stages in a streaming fashion, limiting memory usage.

docling/utils/ (85K chars, 13 files)

Utilities including:

• accelerator_utils.py — Device detection and selection logic
• profiling.py — Pipeline timing instrumentation
• locks.py — Thread-safe resource management for shared model access

docling/service_client/ (76K chars, 6 files)

Async HTTP client built on httpx for communicating with docling-serve. Supports both polling and WebSocket-based result watching.

docling/cli/ (44K chars, 3 files)

CLI built with (likely Click or Typer). Provides commands for conversion, model management, and format listing. The convert command mirrors the Python API's DocumentConverter.convert() with CLI flags for all major options.

8.3 Class Hierarchy

Backend Hierarchy

AbstractDocumentBackend (ABC)
├── PaginatedDocumentBackend
│   ├── PdfDocumentBackend
│   │   ├── DoclingParseDocumentBackend  (default PDF)
│   │   └── PyPdfiumDocumentBackend      (fallback PDF)
│   ├── ImageDocumentBackend
│   └── MetsGbsDocumentBackend
└── DeclarativeDocumentBackend
    ├── HTMLDocumentBackend
    ├── MarkdownDocumentBackend
    ├── CsvDocumentBackend
    ├── MsWordDocumentBackend
    ├── MsPowerpointDocumentBackend
    ├── MsExcelDocumentBackend
    ├── AsciiDocBackend
    ├── WebVTTDocumentBackend
    ├── LatexDocumentBackend
    ├── JatsDocumentBackend
    ├── PatentUsptoDocumentBackend
    └── XBRLDocumentBackend

Pipeline Hierarchy

BasePipeline (ABC)
├── ConvertPipeline
│   ├── PaginatedPipeline
│   │   └── VlmPipeline
│   ├── SimplePipeline
│   └── StandardPdfPipeline
│       └── ThreadedStandardPdfPipeline
└── AsrPipeline

Model Hierarchy

BasePageModel (ABC)
├── BaseOcrModel → EasyOCR, TesseractCli, Tesseract, RapidOCR, OcrMac, AutoOcr, KserveV2
├── BaseLayoutModel → LayoutModel, LayoutObjectDetectionModel
├── BaseTableStructureModel → TableStructureModel, TableStructureModelV2, GraniteVisionTableStructure
├── BaseVlmPageModel (VLM page models)
└── GenericEnrichmentModel
    ├── BaseEnrichmentModel
    └── BaseItemAndImageEnrichmentModel
        ├── PictureDescriptionVlmModel
        ├── PictureDescriptionApiModel
        ├── DocumentPictureClassifier
        └── ChartExtractionModelGraniteVision

Options Hierarchy

PipelineOptions
├── ConvertPipelineOptions
│   └── PaginatedPipelineOptions
│       ├── PdfPipelineOptions
│       └── VlmPipelineOptions
├── AsrPipelineOptions
└── VlmExtractionPipelineOptions

OcrOptions
├── OcrAutoOptions
├── EasyOcrOptions
├── TesseractCliOcrOptions
├── TesseractOcrOptions
├── RapidOcrOptions
├── OcrMacOptions
└── KserveV2OcrOptions

BaseVlmOptions
├── InlineVlmOptions
└── ApiVlmOptions

8.4 Factory Pattern

Docling uses a generic BaseFactory[A] pattern for pluggable model implementations. Each factory:

1. Maintains a registry of model classes keyed by their option type
2. Provides create(options) to instantiate the matching implementation
3. Supports load_from_plugins() to discover external implementations via Python entry points

# Simplified factory usage
from docling.models.factories.ocr_factory import OcrFactory
from docling.datamodel.pipeline_options import EasyOcrOptions

# Factory maps EasyOcrOptions → EasyOCR model class
ocr_model = OcrFactory.create(EasyOcrOptions(lang=["en", "de"]))

Factories:

8.5 Plugin System

External plugins register model implementations via Python entry points in pyproject.toml:

[project.entry-points."docling.ocr"]
my_custom_ocr = "my_package.ocr:MyCustomOcrModel"

At runtime, when allow_external_plugins=True, BaseFactory.load_from_plugins():

1. Scans the docling.ocr (or docling.layout, docling.table_structure) entry point group
2. Imports each discovered module
3. Registers the model class in the factory's registry
4. The model becomes available for use via its option type

8.6 Developing a Custom Backend

To add support for a new document format:

1. Create a new file in docling/backend/ (e.g., my_format_backend.py)
2. Inherit from DeclarativeDocumentBackend (for structured formats) or PaginatedDocumentBackend (for page-based formats)
3. Implement required methods:

from docling.backend.abstract_backend import DeclarativeDocumentBackend

class MyFormatBackend(DeclarativeDocumentBackend):
    @classmethod
    def is_valid(cls, source) -> bool:
        """Check if this backend can handle the source."""
        return source.suffix == ".myformat"

    def convert(self) -> DoclingDocument:
        """Parse the file and return a DoclingDocument."""
        doc = DoclingDocument(name=self.source.stem)
        # ... parse and populate doc ...
        return doc

4. Register the backend in InputFormat and the default FormatOption mapping in document_converter.py.

8.7 Extending a Pipeline

To add a new enrichment stage to StandardPdfPipeline:

1. Create a model class inheriting from BaseEnrichmentModel or BaseItemAndImageEnrichmentModel
2. Implement __call__(self, page, doc_context) to process pages
3. Add the enrichment to the pipeline's stage list in standard_pdf_pipeline.py
4. Add a do_my_enrichment flag to PdfPipelineOptions

8.8 Testing Strategy

The test suite contains 60+ test files organized by component:

tests/
├── test_document_converter.py    # Integration tests
├── test_backend_*.py             # Per-backend unit tests
├── test_pipeline_*.py            # Pipeline tests
├── test_cli_*.py                 # CLI tests
├── test_service_client.py        # Service client tests
├── data/                         # Test fixtures
│   ├── pdf/                      # PDF test documents
│   ├── docx/                     # Word test documents
│   ├── html/                     # HTML test documents
│   └── ...                       # All supported formats
└── groundtruth/                  # Expected output for regression tests
    ├── v1/                       # V1 format groundtruth
    └── v2/                       # V2 format groundtruth

Running tests:

# All tests
pytest

# Skip ML-dependent tests (fast)
pytest -m "not ml_asr"

# Specific component
pytest tests/test_backend_html.py

# Cross-platform tests only
pytest -m cross_platform

Pytest markers:

• ml_asr — Tests requiring Whisper models (slow, GPU-dependent)
• cross_platform — Tests that should pass on all OS platforms

Groundtruth testing: Many tests compare output against checked-in groundtruth files. When making changes that affect output format, update groundtruth files after verifying correctness.

8.9 Code Patterns

Pydantic everywhere: All configuration, options, and data transfer objects are Pydantic BaseModel subclasses. This provides automatic validation, serialization, and documentation.

ABC + Protocol: Base classes use ABC with @abstractmethod for required implementations. The type system enforces that all backends/pipelines/models implement the required interface.

Generic factories: BaseFactory[A] uses Python generics to type-safely map option types to model implementations.

Threaded producer-consumer: The pipeline uses bounded queues between stages. Each stage runs in its own thread, pulling from an input queue and pushing to an output queue. ThreadedQueue handles backpressure and graceful shutdown.

Atomic file rename: ProcessingResult tracks success/failure counts with thread-safe counters.

8.10 Pre-commit and CI

Pre-commit hooks (configured in .pre-commit-config.yaml):

• ruff format — Code formatting
• ruff lint — Linting (import sorting, style rules)
• mypy — Type checking
• uv-lock — Verify lockfile is up to date

# Run all hooks manually
pre-commit run --all-files

# Run specific hook
pre-commit run ruff-format --all-files

9. Integration Points

9.1 RAG Framework Integration

Docling provides chunking capabilities for Retrieval-Augmented Generation (RAG) workflows.

Built-in Chunking

from docling.chunking import HybridChunker

converter = DocumentConverter()
result = converter.convert("paper.pdf")

chunker = HybridChunker()
chunks = list(chunker.chunk(result.document))

for chunk in chunks:
    print(chunk.text)
    print(chunk.meta)  # Source location metadata

LangChain

from langchain_docling import DoclingLoader

loader = DoclingLoader(file_path="paper.pdf")
documents = loader.load()

# Use with a vector store
from langchain_community.vectorstores import Chroma
vectorstore = Chroma.from_documents(documents, embedding_function)

LlamaIndex

from llama_index.readers.docling import DoclingReader

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

Haystack

Docling integrates with Haystack via a converter component for the Haystack pipeline.

9.2 Export Formats

ConversionResult.document (a DoclingDocument from docling-core) supports these export methods:

from pathlib import Path

result = converter.convert("paper.pdf")
doc = result.document

# Save in multiple formats
doc.save_as_markdown(Path("output/paper.md"))
doc.save_as_json(Path("output/paper.json"))
doc.save_as_html(Path("output/paper.html"))

9.3 Docling Ecosystem Integration

9.4 Programmatic API Quick Reference

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    EasyOcrOptions,
    TableStructureOptions,
    TableFormerMode,
)

# Configure
pipeline_options = PdfPipelineOptions(
    do_ocr=True,
    ocr_options=EasyOcrOptions(lang=["en", "de"]),
    do_table_structure=True,
    table_structure_options=TableStructureOptions(mode=TableFormerMode.ACCURATE),
    do_picture_description=True,
    generate_page_images=True,
    images_scale=2.0,
    document_timeout=300.0,
)

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

# Convert
result = converter.convert("paper.pdf")

# Access structured document
doc = result.document
print(doc.title)
print(doc.pages)

# Export
doc.save_as_markdown(Path("output.md"))

# Iterate tables
for table in doc.tables:
    print(table.to_dataframe())

# Chunking for RAG
from docling.chunking import HybridChunker
chunks = list(HybridChunker().chunk(doc))

9.5 Supported Format Matrix

Appendix A: Troubleshooting

A.1 Model Download Failures

Symptom: RuntimeError: "The value of self.artifacts_path=... is not valid"

Resolution:

1. Check internet connectivity (models download from huggingface.co)
2. Verify HF_HOME points to a writable directory with sufficient space
3. Clear corrupted cache: rm -rf ~/.cache/huggingface/hub/models--<model-name>
4. Re-download: docling models download

Tip

In corporate environments with HTTPS inspection, set HF_HUB_DISABLE_TELEMETRY=1 and configure REQUESTS_CA_BUNDLE to point to the corporate CA bundle.

A.2 OCR Not Working

Symptom: Scanned PDFs produce empty or garbled text.

Resolution:

1. Verify OCR is enabled: do_ocr=True (default)
2. Check which OCR engine is selected: OcrAutoOptions auto-detects, but may fall back to a suboptimal engine
3. Install a specific engine: pip install "docling[easyocr]" and set ocr_options=EasyOcrOptions(lang=["en"])
4. Verify language packs are correct for the document language
5. For Tesseract, ensure the binary is on $PATH and language data is installed

A.3 GPU Not Detected

Symptom: Processing is slow; logs show CPU-only inference.

Resolution:

1. Verify PyTorch sees the GPU: python -c "import torch; print(torch.cuda.is_available())"
2. Check DOCLING_DEVICE is not set to cpu
3. For NVIDIA: verify CUDA toolkit and driver versions match PyTorch requirements
4. For Apple Silicon: verify torch.backends.mps.is_available() returns True
5. In Docker: ensure --gpus all is passed and the NVIDIA Container Toolkit is installed

A.4 Memory Issues

Symptom: OutOfMemoryError or process killed during large document processing.

Caution

Large documents (1000+ pages) with high-resolution images and multiple enrichments enabled can consume 32+ GB of RAM. Monitor memory usage and adjust settings accordingly.

Resolution:

1. Reduce perf.page_batch_size
2. Lower images_scale (e.g., from 2.0 to 1.0)
3. Disable unnecessary enrichments
4. Set limits.max_num_pages to process documents in chunks
5. Use generate_page_images=False if page images are not needed

A.5 HTML Rendering Issues

Symptom: ImportError: "Playwright is required for HTML rendering..."

Resolution:

pip install "docling[htmlrender]"
playwright install chromium

For Docker deployments, ensure Chromium dependencies are installed:

playwright install-deps chromium

A.6 LaTeX Timeout

Symptom: LaTeX conversion hangs or times out.

Resolution: Increase the parse timeout (default 30 seconds):

from docling.datamodel.pipeline_options import LatexBackendOptions

options = LatexBackendOptions(parse_timeout=120)  # 2 minutes

Malformed LaTeX (unclosed environments, recursive macros) can cause pathological parsing behavior. The timeout prevents infinite hangs.

A.7 Format Not Recognized

Symptom: ConversionError: "Conversion failed because the provided file has no recognizable format..."

Resolution:

1. Verify the file extension matches a supported format
2. Check that the file is not corrupt (open it manually)
3. For format .txt: As of the source version, plain text is not a supported input format (see issue #3259)
4. Ensure the format's backend is included in the allowed_formats configuration