Docling User Guide

Docling is an open-source Python framework that converts documents from 17 input formats into structured output. It reads PDFs, Word documents, PowerPoint slides, HTML pages, images, LaTeX files, spreadsheets, audio/video, and more, then produces clean Markdown, JSON, YAML, HTML, or plain text. Under the hood, Docling uses AI models for layout analysis, OCR, table structure recognition, and optional vision-language model (VLM) conversion.

Key features:

• 17 input formats — PDF, DOCX, PPTX, HTML, images (JPG/PNG/TIFF/BMP/WebP), LaTeX, CSV, Excel, Markdown, AsciiDoc, audio/video, XML (USPTO/JATS/XBRL), METS, WebVTT, and Docling JSON
• 8 output formats — Markdown, JSON, YAML, HTML, HTML split-page, plain text, DocTags, and WebVTT
• AI-powered analysis — layout detection, table structure recognition, OCR, formula enrichment, picture classification, chart data extraction
• Two conversion pipelines — standard (layout model + OCR) and VLM (vision-language model for end-to-end conversion)
• Six OCR engines — EasyOCR, Tesseract (CLI and library), RapidOCR, macOS native OCR, and remote KServe v2
• GPU acceleration — supports CUDA, Apple MPS, and Intel XPU devices
• CLI and Python API — use docling convert from the terminal or DocumentConverter in code
• Plugin architecture — extensible with third-party format handlers and enrichment models

1. Quick Start

Tip

Docling works out of the box with sensible defaults. The minimal example below converts a PDF to Markdown with no configuration needed.

Prerequisites

• Python 3.10 or later
• pip (or uv for faster installs)
• 2 GB+ free disk space for model artifacts (downloaded automatically on first run)

Install

pip install docling

Convert your first document

CLI:

docling convert my-report.pdf --to md

Expected output:

Processed my-report.pdf in 12.3s
Output written to ./my-report.md

Python:

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("my-report.pdf")
print(result.document.export_to_markdown())

Next steps

• See Section 2 for installation extras (OCR engines, GPU support, audio processing)
• See Section 3 for environment variables and configuration options
• See Section 4 for detailed CLI and Python API usage
• See Section 5 for ready-to-use recipes for common tasks

2. Installation

Base install

pip install docling

The base install includes PDF processing (via docling-parse), DOCX/PPTX/HTML/CSV/Markdown conversion, layout analysis models, and table structure recognition. Model artifacts are downloaded automatically on first use.

Optional extras

Docling provides several extras for additional capabilities:

Install multiple extras at once:

pip install "docling[ocr,gpu,vlm]"

Important

GPU support requires a compatible NVIDIA driver and CUDA toolkit already installed on your system. Docling's gpu extra installs the Python CUDA bindings but not the system-level driver.

Install from source (with uv)

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

Verify installation

docling convert --version

Expected output:

docling version X.Y.Z

You can also verify the Python API:

from docling.document_converter import DocumentConverter
converter = DocumentConverter()
print("Docling loaded successfully")

System dependencies for OCR

If you plan to use Tesseract OCR, install the system package separately:

For additional Tesseract languages:

# Ubuntu example — install German and French
sudo apt install tesseract-ocr-deu tesseract-ocr-fra

Warning

On Python 3.12 running in Databricks Serverless environments, Docling may crash with a SIGABRT signal due to library conflicts. If you encounter this, pin to an earlier Python version or run outside Databricks Serverless.

Install troubleshooting

Slow first run: The first conversion downloads model artifacts (approximately 1-2 GB). Subsequent runs use the cached models. You can pre-download artifacts with:

docling download

Conflicting dependencies: If you encounter dependency conflicts, use a virtual environment:

python -m venv docling-env
source docling-env/bin/activate  # Linux/macOS
# docling-env\Scripts\activate   # Windows
pip install docling

3. Configuration

Environment variables

Docling reads several environment variables for runtime configuration:

Set environment variables before running Docling:

# Linux/macOS
export DOCLING_NUM_THREADS=8
export DOCLING_DEVICE=cuda
docling convert my-document.pdf

# Windows (PowerShell)
$env:DOCLING_NUM_THREADS = "8"
$env:DOCLING_DEVICE = "cuda"
docling convert my-document.pdf

Common option combinations

High-quality PDF conversion (slower, more accurate):

docling convert document.pdf --to md --ocr --table-mode accurate --force-ocr

Fast bulk processing (less accurate, much faster):

docling convert ./documents/ --to md --table-mode fast --no-ocr --num-threads 8

GPU-accelerated processing:

docling convert document.pdf --to md --device cuda --num-threads 8

VLM pipeline (vision-language model):

docling convert document.pdf --to md --pipeline vlm --vlm-model granite_docling

Note

For a full reference of all configuration options, pipeline internals, and advanced tuning, see the Admin Guide at docling-project/docling.

4. Core Usage

4.1 CLI conversion

The docling convert command is the primary CLI entry point. It accepts files, directories, and URLs as sources.

Convert a single file

docling convert report.pdf --to md

Output is written to ./report.md in the current directory by default.

Specify output directory

docling convert report.pdf --to md --output ./converted/

Convert to multiple formats

docling convert report.pdf --to md --to json --to html

This produces report.md, report.json, and report.html in the output directory.

Convert a directory of documents

docling convert ./documents/ --to md

Docling processes every supported file in the directory. Use --from to restrict input formats:

docling convert ./documents/ --from pdf --from docx --to md

Convert from a URL

docling convert https://example.com/paper.pdf --to md

For URLs requiring authentication, pass headers as a JSON string:

docling convert https://example.com/paper.pdf --to md \
  --headers '{"Authorization": "Bearer YOUR_TOKEN"}'

Control verbosity

# Info-level logging
docling convert report.pdf --to md -v

# Debug-level logging
docling convert report.pdf --to md -vv

Tip

Use --profiling to see a performance summary after conversion, or --save-profiling profile.json to save detailed timing data to a file.

Stop on first error

By default, Docling continues processing remaining documents if one fails. To stop immediately:

docling convert ./documents/ --to md --abort-on-error

Set a per-document timeout

docling convert ./large-docs/ --to md --document-timeout 120

This aborts conversion of any single document that exceeds 120 seconds.

4.2 Python API

The Python API provides finer control over conversion options and programmatic access to results.

Basic conversion

from docling.document_converter import DocumentConverter

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

# Access the converted document
doc = result.document

# Export to different formats
markdown = doc.export_to_markdown()
json_str = doc.export_to_json()
yaml_str = doc.export_to_yaml()
html_str = doc.export_to_html()
text_str = doc.export_to_text()

Check conversion status

result = converter.convert("report.pdf")

print(f"Status: {result.status}")
print(f"Timings: {result.timings}")
if result.errors:
    for error in result.errors:
        print(f"Error: {error}")

Restrict allowed input formats

from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import InputFormat

converter = DocumentConverter(
    allowed_formats=[InputFormat.PDF, InputFormat.DOCX]
)
result = converter.convert("report.pdf")

Custom PDF options

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

pdf_options = PdfPipelineOptions()
pdf_options.do_ocr = True
pdf_options.do_table_structure = True
pdf_options.table_structure_options.mode = "accurate"

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

Batch conversion

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
sources = ["report1.pdf", "report2.pdf", "slides.pptx", "doc.docx"]

for result in converter.convert_all(sources):
    print(f"{result.input.file}: {result.status}")
    md = result.document.export_to_markdown()
    with open(f"{result.input.file.stem}.md", "w") as f:
        f.write(md)

Convert from string

from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import InputFormat

converter = DocumentConverter()
html_content = "<html><body><h1>Hello</h1><p>World</p></body></html>"

result = converter.convert_string(html_content, InputFormat.HTML)
print(result.document.export_to_markdown())

Expected output:

# Hello

World

4.3 Output formats

4.4 OCR options

Docling supports six OCR engines. By default, OCR is enabled and the engine is selected automatically.

Important

The macOS native OCR engine (ocr_mac) is an optional extra. Install it separately if needed. It is only available on macOS systems.

Specify OCR language

docling convert document.pdf --to md --ocr-engine easyocr --ocr-lang en,de,fr

Force full-page OCR

By default, Docling only applies OCR to regions where the PDF backend cannot extract text. Use --force-ocr to replace all extracted text with OCR output:

docling convert scanned-doc.pdf --to md --force-ocr

Disable OCR entirely

docling convert digital-doc.pdf --to md --no-ocr

Tesseract page segmentation modes

When using Tesseract, you can set the page segmentation mode (PSM):

docling convert document.pdf --to md --ocr-engine tesseract_cli --psm 6

4.5 VLM pipeline

The VLM (vision-language model) pipeline uses a large vision model to convert documents end-to-end, rather than the traditional layout-analysis + OCR approach. This can produce better results for complex layouts at the cost of higher compute.

docling convert document.pdf --to md --pipeline vlm --vlm-model granite_docling

In Python:

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

vlm_options = VlmPipelineOptions()

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

Note

The VLM pipeline requires the vlm extra (pip install "docling[vlm]"). It is significantly more resource-intensive than the standard pipeline and benefits greatly from GPU acceleration.

4.6 ASR pipeline (audio/video)

Docling can transcribe audio and video files using Whisper-based ASR models.

Supported audio/video formats: WAV, MP3, M4A, AAC, OGG, FLAC, MP4, AVI, MOV

docling convert meeting.mp3 --to md --asr-model whisper_tiny

Available ASR model presets:

MLX variants (whisper_tiny_mlx, whisper_small_mlx, etc.) are available for Apple Silicon Macs. Native variants (whisper_tiny_native, etc.) use the native Whisper implementation.

# macOS Apple Silicon — use MLX variant for best performance
docling convert podcast.mp3 --to md --asr-model whisper_small_mlx

# Output as WebVTT subtitles
docling convert video.mp4 --to vtt --asr-model whisper_medium

4.7 Enrichments

Enrichments are optional post-processing steps that extract additional information from documents.

docling convert paper.pdf --to md \
  --enrich-code --enrich-formula --enrich-picture-classes

In Python, enrichments are configured through pipeline options specific to each format.

4.8 Image export modes

Control how images from the source document appear in the output:

# Save images as separate files
docling convert brochure.pdf --to md --image-export-mode referenced --output ./output/

4.9 PDF backend options

Docling supports two PDF backends:

docling convert document.pdf --to md --pdf-backend pypdfium2

4.10 Table structure options

Disable table detection entirely:

docling convert document.pdf --to md --no-tables

4.11 Downloading model artifacts

Model artifacts are downloaded automatically on first use. To pre-download:

# Download all standard model artifacts
docling download

# Download a specific HuggingFace model repo
docling download-hf-repo <repo-id>

To use a custom artifacts location:

docling convert document.pdf --to md --artifacts-path /path/to/models/

4.12 Service client (experimental)

If you have a running instance of docling-serve, you can use the DoclingServiceClient to send conversion requests remotely:

from docling.service_client import DoclingServiceClient

client = DoclingServiceClient(url="http://localhost:5000")
result = client.convert("document.pdf")
print(result.document.export_to_markdown())

Or configure via environment variables:

export DOCLING_SERVICE_URL=http://localhost:5000
export DOCLING_SERVICE_API_KEY=your-key

The service client supports convert(), convert_all(), submit() (async), and chunk().

4.13 External plugins

Docling supports third-party plugins for additional format handlers and enrichment models.

# List available external plugins
docling convert --show-external-plugins

# Enable external plugins for a conversion
docling convert document.pdf --to md --allow-external-plugins

Warning

External plugins execute third-party code. Only enable --allow-external-plugins with plugins you trust. By default, external plugins are not loaded.

4.14 Debug visualization

Docling can generate visual overlays for debugging conversion quality:

# Show layout bounding boxes on page images
docling convert document.pdf --to md --show-layout

# Visualize specific detection stages
docling convert document.pdf --to md \
  --debug-visualize-cells \
  --debug-visualize-ocr \
  --debug-visualize-layout \
  --debug-visualize-tables

These flags produce annotated images showing what the models detected on each page, useful for diagnosing conversion quality issues.

5. Common Tasks

5.1 Convert a PDF to Markdown

docling convert report.pdf --to md --output ./output/

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("report.pdf")
with open("report.md", "w", encoding="utf-8") as f:
    f.write(result.document.export_to_markdown())

5.2 Batch convert an entire directory

docling convert ./papers/ --to md --to json --output ./converted/ --num-threads 8

from docling.document_converter import DocumentConverter
from pathlib import Path

converter = DocumentConverter()
sources = list(Path("./papers/").glob("*.pdf"))

for result in converter.convert_all(sources):
    out_path = Path("./converted/") / f"{result.input.file.stem}.md"
    out_path.write_text(result.document.export_to_markdown(), encoding="utf-8")
    print(f"Converted: {result.input.file.name} -> {out_path.name}")

5.3 Use the VLM pipeline for complex layouts

pip install "docling[vlm,gpu]"
docling convert complex-layout.pdf --to md --pipeline vlm --vlm-model granite_docling --device cuda

5.4 Extract tables from a PDF

docling convert financial-report.pdf --to json --table-mode accurate

The JSON output contains structured table data with rows, columns, and cell content. To inspect tables programmatically:

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("financial-report.pdf")

# Iterate through document items to find tables
for item in result.document.tables:
    print(item.export_to_dataframe())

5.5 Export figures from a document

docling convert illustrated-doc.pdf --to md \
  --image-export-mode referenced \
  --output ./output/

This saves each extracted figure as a separate image file in the output directory and links them from the Markdown.

5.6 Force full-page OCR on a scanned document

docling convert scanned-document.pdf --to md --force-ocr --ocr-engine easyocr --ocr-lang en

5.7 Convert with a specific OCR engine

# Using Tesseract with German language
docling convert german-doc.pdf --to md --ocr-engine tesseract_cli --ocr-lang deu

# Using RapidOCR for speed
docling convert quick-scan.pdf --to md --ocr-engine rapidocr

# Using macOS native OCR
docling convert note.pdf --to md --ocr-engine ocr_mac

5.8 Transcribe audio to Markdown

pip install "docling[asr]"
docling convert interview.mp3 --to md --asr-model whisper_small

5.9 Convert a password-protected PDF

docling convert protected.pdf --to md --pdf-password "my-secret-password"

5.10 Convert HTML with browser rendering

For complex HTML pages that rely on JavaScript rendering:

pip install "docling[htmlrender]"
docling convert https://example.com/complex-page.html --to md

5.11 Convert LaTeX to Markdown

docling convert paper.tex --to md

LaTeX documents (.tex, .latex) are parsed directly and converted to the target format without requiring a LaTeX installation.

5.12 Use GPU acceleration

# Automatic device detection
docling convert document.pdf --to md --device auto

# Explicit CUDA device
docling convert document.pdf --to md --device cuda

# Specific GPU
docling convert document.pdf --to md --device cuda:1

# Apple Silicon MPS
docling convert document.pdf --to md --device mps

5.13 Convert Word documents

docling convert presentation.pptx report.docx --to md --output ./converted/

Supported Word extensions: .docx, .dotx, .docm, .dotm. Supported PowerPoint extensions: .pptx, .potx, .ppsx, .pptm, .potm, .ppsm.

5.14 Convert a URL with custom headers

docling convert https://internal.example.com/doc.pdf --to md \
  --headers '{"Authorization": "Bearer tok_abc123", "Cookie": "session=xyz"}'

5.15 Run with profiling

docling convert large-doc.pdf --to md --profiling --save-profiling timing.json

The --profiling flag prints a summary table showing time spent in each pipeline phase. --save-profiling writes the full timing data to a JSON file for further analysis.

6. Troubleshooting

Error: SIGABRT crash on Python 3.12 in Databricks Serverless

Cause: Library-level conflicts between Docling's native dependencies and the Databricks Serverless runtime on Python 3.12.

Solution: Use Python 3.10 or 3.11 in your Databricks environment, or run Docling outside of Databricks Serverless.

Prevention: Pin your Python version in Databricks cluster configuration.

Error: File format '.txt' not allowed

Cause: Prior to version 2.81.0, .txt files were not mapped to any input format. In 2.81.0 and later, .txt is mapped to InputFormat.MD (Markdown). If you still encounter this error, your Docling version may be outdated.

Solution: Upgrade Docling:

pip install --upgrade docling

If the issue persists, explicitly allow Markdown format:

docling convert notes.txt --from md --to md

Prevention: Keep Docling updated and use --from to explicitly set the input format for ambiguous extensions.

Error: ChartExtractionModelGraniteVisionV4 crashes on init

Cause: Incompatibility with transformers version 5.x. The chart extraction enrichment model requires an earlier version of the transformers library.

Solution: Downgrade transformers:

pip install "transformers<5.0"

Or disable chart extraction if you do not need it (omit --enrich-chart-extraction).

Prevention: Check Docling's release notes for compatible dependency versions when upgrading.

Caution

Downgrading transformers may affect other packages in your environment that depend on version 5.x. Use a dedicated virtual environment for Docling if you have conflicting requirements.

Error: 2x pipeline regression in version 2.81.0

Cause: Performance regression in version 2.81.0 compared to 2.74.0, where conversion takes approximately twice as long.

Solution: If speed is critical, pin to version 2.74.0:

pip install docling==2.74.0

Or check for patches in later releases that may address the regression.

Prevention: Test performance after upgrades, especially for batch processing workflows.

Error: DOCX blank images or missing text

Cause: Certain DOCX files with embedded images (particularly EMF format) may not convert all content. EMF (Enhanced Metafile) picture extraction from DOCX has known limitations.

Solution: Convert the DOCX to PDF first (using LibreOffice or Microsoft Word), then process the PDF with Docling:

libreoffice --headless --convert-to pdf problematic.docx
docling convert problematic.pdf --to md

Prevention: For DOCX files with complex embedded media, the PDF-first workflow is more reliable.

Error: DOCX headers not converting to Markdown headers

Cause: Some DOCX files use visual formatting (bold + large font) instead of Word's built-in heading styles. Docling relies on heading styles for Markdown header detection.

Solution: If you control the source document, apply proper heading styles (Heading 1, Heading 2, etc.) in Word. Otherwise, post-process the Markdown output to promote visually large text to headers.

Error: Parenthesis causes duplicated text

Cause: A known parsing issue where certain parenthesized content is duplicated in the output.

Solution: Post-process the output to remove duplicates, or check for a fix in newer Docling releases.

Error: HTML anchors stripped in Markdown output

Cause: When converting HTML to Markdown, anchor tags (<a>) may be stripped, losing internal links.

Solution: Use --to html instead of --to md if you need to preserve HTML anchors. Alternatively, use --to json and post-process the structured output to reconstruct links.

Error: Meaningless output from OCR

Cause: Some OCR engines produce poor results on certain document types, particularly when the wrong engine or language is selected.

Solution:

1. Try a different OCR engine:

docling convert document.pdf --to md --ocr-engine easyocr --ocr-lang en

2. Use --force-ocr to ensure OCR processes every page:

docling convert document.pdf --to md --force-ocr --ocr-engine tesseract_cli

3. Use the VLM pipeline as an alternative:

docling convert document.pdf --to md --pipeline vlm

Warning

If OCR output is consistently poor, verify that you have the correct OCR language packs installed and that the source document has sufficient image quality (300 DPI minimum recommended for scanned documents).

Error: Model download fails or times out

Cause: Network issues during automatic model artifact download.

Solution: Pre-download models explicitly:

docling download

Or set a custom artifacts path and manually place model files:

docling convert document.pdf --to md --artifacts-path /path/to/local/models/

Error: Out of memory during conversion

Cause: Large documents or GPU models exceeding available RAM or VRAM.

Solution:

• Reduce thread count: --num-threads 2
• Use CPU instead of GPU: --device cpu
• Process fewer pages at a time: --page-batch-size 2
• Use --table-mode fast instead of accurate
• Switch from VLM to standard pipeline

7. FAQ

Q: What Python versions does Docling support?

Docling supports Python 3.10 and later. Be aware of the known SIGABRT issue on Python 3.12 in Databricks Serverless environments.

Q: Do I need a GPU to run Docling?

No. Docling works on CPU by default. GPU acceleration (CUDA, MPS, XPU) speeds up AI model inference significantly but is entirely optional. Set --device cpu to force CPU processing.

Q: How much disk space do the models need?

The standard models require approximately 1-2 GB. VLM and ASR models are additional. Models are downloaded once and cached locally. Use docling download to pre-download, or --artifacts-path to control where they are stored.

Q: Can Docling handle scanned PDFs?

Yes. Docling applies OCR to image-based regions automatically. For fully scanned PDFs, use --force-ocr to process all pages through OCR rather than attempting text extraction first.

Q: What is the difference between the standard and VLM pipeline?

The standard pipeline uses separate models for layout detection, text extraction, OCR, and table recognition. It is faster and lighter. The VLM pipeline uses a single vision-language model to interpret pages end-to-end. It can handle complex layouts better but requires more compute (GPU recommended).

Q: Can Docling process password-protected PDFs?

Yes. Use --pdf-password "your-password" on the CLI or configure it through PdfFormatOption in the Python API.

Q: How do I convert audio or video files?

Install the ASR extra (pip install "docling[asr]"), then use:

docling convert recording.mp3 --to md --asr-model whisper_small

Output can be Markdown (transcription) or WebVTT (--to vtt) for subtitles.

Q: Can I run Docling as a web service?

Docling itself is a library and CLI tool, not a web server. The companion project docling-serve provides a REST API. You can connect to it using DoclingServiceClient after installing the remote-serving extra.

Q: What is the DocTags output format?

DocTags is Docling's internal tagged representation of document structure. It preserves layout and semantic information in a compact format. Use --to doctags to produce this output. It is primarily useful for downstream Docling tooling rather than human reading.

Q: How do I process only certain file types in a mixed directory?

Use the --from flag to restrict which input formats Docling processes:

# Only process PDFs and Word documents
docling convert ./mixed-folder/ --from pdf --from docx --to md

Q: Can I use Docling in a Docker container?

Yes. Install Docling in your Docker image as you would on any Linux system. If you need Tesseract OCR, include apt-get install tesseract-ocr in your Dockerfile. For GPU support, use an NVIDIA CUDA base image.