Installation

Relevant source files

• .github/workflows/checks.yml
• README.md
• docs/examples/minimal_vlm_pipeline.py
• docs/index.md
• docs/usage/index.md
• mkdocs.yml

This page provides instructions for installing Docling and its dependencies. It covers the basic installation, optional feature dependencies (extras), system-level requirements, and platform-specific considerations.

For information about using Docling after installation, see Quick Start. For details on configuring GPU acceleration, see GPU and Hardware Acceleration.

---

Basic Installation

The simplest way to install Docling is via pip:

This installs the core Docling package with support for:

• PDF processing (DoclingParse and PyPdfium2 backends)
• Office formats (DOCX, XLSX, PPTX via python-docx, openpyxl, python-pptx)
• Web formats (HTML, Markdown via BeautifulSoup, marko)
• Image formats (PNG, JPEG, TIFF via Pillow)
• LaTeX, CSV, and other declarative backends
• Basic layout detection models

Python Version Requirements:

• Python 3.10 or higher (3.9 support dropped in Docling 2.70.0)
• Tested on Python 3.10, 3.11, 3.12, 3.13, and 3.14

Platform Support:

• macOS (x86_64 and arm64/Apple Silicon)
• Linux (x86_64 and arm64)
• Windows (x86_64 and arm64)

Sources: README.md58-68 .github/workflows/checks.yml65-333

---

Installation Options by Feature

Installation Extras Matrix

Docling uses Python extras to provide optional functionality. The following table summarizes available extras and their use cases:

Extra	Purpose	Key Packages	System Dependencies
easyocr	EasyOCR engine for scanned PDFs/images	easyocr	None (pure Python/PyTorch)
tesserocr	Tesseract OCR engine (fastest, most accurate)	tesserocr	tesseract-ocr, libleptonica-dev, libtesseract-dev, Python dev headers
rapidocr	RapidOCR engine (lightweight)	rapidocr-onnxruntime	None (ONNX runtime)
vlm	Vision Language Models (GraniteDocling, etc.)	transformers, accelerate, torch, mlx (macOS)	None (model weights downloaded on first use)
asr	Audio transcription (Whisper models)	transformers, torch	ffmpeg

Installing with Extras

To install Docling with specific extras, use square brackets:

Note: The tesserocr extra requires compilation and system dependencies (see below). If you don't have Python development headers installed, you can omit tesserocr and use easyocr or rapidocr instead.

Sources: .github/workflows/checks.yml310-385

---

System Dependencies

For OCR with Tesseract

The tesserocr extra provides the fastest and most accurate OCR but requires system-level packages:

Ubuntu/Debian:

macOS (Homebrew):

Language Packs: Install additional language packs as needed:

Environment Variable: Set TESSDATA_PREFIX to point to the tessdata directory:

For Audio Processing

Audio and video transcription (ASR pipeline) requires FFmpeg:

Ubuntu/Debian:

macOS:

For Office Format Support (Optional)

LibreOffice is used as a fallback for complex Office documents:

Ubuntu/Debian:

Note: LibreOffice is not required for basic DOCX/XLSX/PPTX support, which uses pure Python libraries (python-docx, openpyxl, python-pptx).

Sources: .github/workflows/checks.yml82-223

---

Installation Flow Diagram

Installation Flow Diagram - Shows how the pip install command resolves to core and optional dependencies, and where model artifacts are cached.

Sources: .github/workflows/checks.yml96-243 README.md58-68

---

Component to Extra Mapping

Component to Extra Mapping - Shows which installation extras enable which processing pipelines and model components.

Sources: README.md31-43 docs/examples/minimal_vlm_pipeline.py10-11

---

Platform-Specific Considerations

macOS with Apple Silicon (arm64)

Docling provides optimized support for Apple Silicon through the MLX framework:

1. MLX Runtime for VLMs: When installing the vlm extra on macOS arm64, the mlx package is included for accelerated vision language model inference.

2. Automatic Selection: The VlmPipeline automatically detects Apple Silicon and uses MLX when available, falling back to Transformers otherwise.

3. Installation:

4. Usage: The MlxVlmEngineOptions class configures MLX-specific parameters. See Inline VLM Models for details.

GPU Acceleration

For GPU-accelerated inference on NVIDIA, AMD, or Intel GPUs:

1. PyTorch Backend: Install PyTorch with the appropriate CUDA/ROCm support before installing Docling:

2. Install Docling: Then install Docling with desired extras:

3. Configuration: Set the AcceleratorDevice in pipeline options. See GPU and Hardware Acceleration for detailed configuration.

Windows

Docling works on Windows x86_64 and arm64 with the following considerations:

1. Tesseract OCR: Install Tesseract from the official installer: https://github.com/UB-Mannheim/tesseract/wiki
2. FFmpeg: Install from https://ffmpeg.org/download.html or via package managers like Chocolatey
3. Python Dev Headers: Usually included with standard Python installation from python.org

Sources: docs/examples/minimal_vlm_pipeline.py82-90 README.md67

---

Verification

After installation, verify Docling is working correctly:

CLI Verification

Python API Verification

Model Download Verification

On first use, Docling downloads ML models to cache directories:

• Layout models: ~/.cache/huggingface/hub/ (EGRET, HERON)
• VLM models: ~/.cache/huggingface/hub/ (GraniteDocling, etc.)
• EasyOCR models: ~/.EasyOCR/model/

These models are downloaded once and reused for subsequent runs.

Sources: .github/workflows/checks.yml98-174 README.md73-93

---

Alternative Package Managers

Using uv

The Docling project uses uv for development and CI/CD. To install with uv:

Benefits of uv:

• Faster dependency resolution
• Better caching
• Used in Docling's CI/CD pipeline

Sources: .github/workflows/checks.yml35-95 README.md17

---

Troubleshooting

Common Installation Issues

Issue: tesserocr fails to compile

• Cause: Missing system dependencies or Python development headers
• Solution:
  1. Install system dependencies (see System Dependencies)
  2. Ensure Python development headers are installed (python3-dev on Ubuntu)
  3. Alternatively, use easyocr or rapidocr instead

Issue: Models not downloading

• Cause: Network issues or firewall blocking Hugging Face Hub
• Solution:
  1. Set longer timeouts: export HF_HUB_DOWNLOAD_TIMEOUT=90
  2. Configure proxy if behind corporate firewall
  3. Use docling models download CLI to manually download models

Issue: Out of memory during VLM inference

• Cause: Large models require significant RAM/VRAM
• Solution:
  1. Use smaller model variants (e.g., GraniteDocling-258M instead of 8B)
  2. Configure smaller batch sizes in VlmPipelineOptions
  3. Use API-based inference instead of inline models

Sources: .github/workflows/checks.yml13-14 .github/workflows/checks.yml323-396

---

Next Steps

After installing Docling:

1. Quick Start: Learn basic usage patterns in Quick Start
2. Examples: Explore conversion examples in Examples
3. Configuration: Learn about pipeline options in Configuration and Pipeline Options
4. GPU Acceleration: Configure hardware acceleration in GPU and Hardware Acceleration

Sources: README.md71-85 docs/index.md23-34