# 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

```bash
pip install docling
```

### Convert your first document

**CLI:**

```bash
docling convert my-report.pdf --to md
```

Expected output:

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

**Python:**

```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

```bash
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:

| Extra | Install command | What it adds |
|---|---|---|
| OCR support | `pip install "docling[ocr]"` | EasyOCR, Tesseract bindings, RapidOCR |
| ASR (audio) | `pip install "docling[asr]"` | Whisper models for audio/video transcription |
| VLM pipeline | `pip install "docling[vlm]"` | Vision-language model conversion |
| GPU (CUDA) | `pip install "docling[gpu]"` | CUDA-accelerated inference |
| HTML rendering | `pip install "docling[htmlrender]"` | Browser-based HTML rendering for complex pages |
| Remote serving | `pip install "docling[remote-serving]"` | Client for docling-serve |

Install multiple extras at once:

```bash
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)

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

### Verify installation

```bash
docling convert --version
```

Expected output:

```
docling version X.Y.Z
```

You can also verify the Python API:

```python
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:

| OS | Command |
|---|---|
| Ubuntu/Debian | `sudo apt install tesseract-ocr` |
| macOS | `brew install tesseract` |
| Windows | Download installer from [UB Mannheim builds](https://github.com/UB-Mannheim/tesseract/wiki) |
| Fedora/RHEL | `sudo dnf install tesseract` |

For additional Tesseract languages:

```bash
# 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:

```bash
docling download
```

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

```bash
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:

| Variable | Purpose | Default |
|---|---|---|
| `DOCLING_NUM_THREADS` | Number of CPU threads for processing | 4 |
| `OMP_NUM_THREADS` | Fallback thread count (used if `DOCLING_NUM_THREADS` not set) | System default |
| `DOCLING_DEVICE` | Hardware device: `auto`, `cpu`, `cuda`, `cuda:0`, `mps`, `xpu` | `auto` |
| `DOCLING_CUDA_USE_FLASH_ATTENTION2` | Enable Flash Attention 2 for CUDA inference | Not set (disabled) |
| `DOCLING_PARTITION_SIZE` | Partition size for multiprocessing | Internal default |
| `DOCLING_HTML_WORKERS` | Number of workers for HTML rendering | Internal default |
| `DOCLING_SERVICE_URL` | URL for remote docling-serve instance | Not set |
| `DOCLING_SERVICE_API_KEY` | API key for remote docling-serve | Not set |

Set environment variables before running Docling:

```bash
# 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):**

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

**Fast bulk processing (less accurate, much faster):**

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

**GPU-accelerated processing:**

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

**VLM pipeline (vision-language model):**

```bash
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](/guides/docling-project/docling/admin-guide/).

---

## 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

```bash
docling convert report.pdf --to md
```

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

#### Specify output directory

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

#### Convert to multiple formats

```bash
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

```bash
docling convert ./documents/ --to md
```

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

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

#### Convert from a URL

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

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

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

#### Control verbosity

```bash
# 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:

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

#### Set a per-document timeout

```bash
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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:

```markdown
# Hello

World
```

### 4.3 Output formats

| Format | CLI flag | File extension | Description |
|---|---|---|---|
| Markdown | `--to md` | `.md` | Clean Markdown with tables and headings |
| JSON | `--to json` | `.json` | Structured document JSON (DoclingDocument schema) |
| YAML | `--to yaml` | `.yaml` | YAML representation of the document structure |
| HTML | `--to html` | `.html` | Single-page HTML |
| HTML split-page | `--to html_split_page` | `.html` | One HTML file per page |
| Plain text | `--to text` | `.txt` | Stripped-down plain text |
| DocTags | `--to doctags` | `.doctags` | Docling's internal tagged format |
| WebVTT | `--to vtt` | `.vtt` | Subtitle/caption format (for audio/video input) |

### 4.4 OCR options

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

| Engine | CLI value | Notes |
|---|---|---|
| Auto | `--ocr-engine auto` | Picks the best available engine |
| EasyOCR | `--ocr-engine easyocr` | Good multilingual support, GPU-capable |
| Tesseract CLI | `--ocr-engine tesseract_cli` | Requires system Tesseract install |
| Tesseract (pytesseract) | `--ocr-engine tesseract` | Python bindings for Tesseract |
| RapidOCR | `--ocr-engine rapidocr` | Lightweight, fast |
| macOS native | `--ocr-engine ocr_mac` | Uses Apple Vision framework (macOS only) |
| KServe v2 | `--ocr-engine kserve_v2` | Remote OCR via KServe-compatible server |

> [!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

```bash
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:

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

#### Disable OCR entirely

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

#### Tesseract page segmentation modes

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

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

| PSM | Description |
|---|---|
| 0 | Orientation and script detection only |
| 1 | Automatic with OSD |
| 3 | Fully automatic (default) |
| 4 | Assume single column |
| 6 | Assume single uniform block |
| 7 | Treat as single text line |
| 8 | Treat as single word |
| 11 | Sparse text |
| 13 | Raw line |

### 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.

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

In Python:

```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

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

Available ASR model presets:

| Preset | Size | Speed | Accuracy |
|---|---|---|---|
| `whisper_tiny` (default) | ~39 MB | Fastest | Lower |
| `whisper_base` | ~74 MB | Fast | Fair |
| `whisper_small` | ~244 MB | Moderate | Good |
| `whisper_medium` | ~769 MB | Slow | Better |
| `whisper_large` | ~1.5 GB | Slowest | Best |
| `whisper_turbo` | Varies | Fast | Good |

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.

```bash
# 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.

| Enrichment | CLI flag | What it does |
|---|---|---|
| Code blocks | `--enrich-code` | Identifies and labels code blocks |
| Formulas | `--enrich-formula` | Detects and processes mathematical formulas |
| Picture classes | `--enrich-picture-classes` | Classifies images (chart, diagram, photo, etc.) |
| Picture descriptions | `--enrich-picture-description` | Generates text descriptions of images |
| Chart extraction | `--enrich-chart-extraction` | Extracts structured data from charts |

```bash
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:

| Mode | CLI flag | Behavior |
|---|---|---|
| Placeholder | `--image-export-mode placeholder` | Replaces images with `[image]` placeholders |
| Embedded | `--image-export-mode embedded` | Base64-encodes images inline (default) |
| Referenced | `--image-export-mode referenced` | Saves images as files, adds relative paths |

```bash
# 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:

| Backend | CLI flag | Characteristics |
|---|---|---|
| docling-parse | `--pdf-backend docling_parse` | Default. Purpose-built for Docling, better layout fidelity |
| pypdfium2 | `--pdf-backend pypdfium2` | Alternative, based on PDFium |

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

### 4.10 Table structure options

| Mode | CLI flag | Characteristics |
|---|---|---|
| Accurate | `--table-mode accurate` | Default. Uses deep learning model for table detection |
| Fast | `--table-mode fast` | Heuristic-based, faster but less precise |

Disable table detection entirely:

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

### 4.11 Downloading model artifacts

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

```bash
# 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:

```bash
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:

```python
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:

```bash
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.

```bash
# 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:

```bash
# 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

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

```python
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

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

```python
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

```bash
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

```bash
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:

```python
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

```bash
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

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

### 5.7 Convert with a specific OCR engine

```bash
# 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

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

### 5.9 Convert a password-protected PDF

```bash
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:

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

### 5.11 Convert LaTeX to Markdown

```bash
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

```bash
# 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

```bash
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

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

### 5.15 Run with profiling

```bash
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:

```bash
pip install --upgrade docling
```

If the issue persists, explicitly allow Markdown format:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

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

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

3. Use the VLM pipeline as an alternative:

```bash
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:

```bash
docling download
```

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

```bash
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:

```bash
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:

```bash
# 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.

---

_Generated May 2026 from docling-project/docling at 2bb0fa6. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._