Optional Dependency Management#

Docling separates core functionality from packages that carry licensing risk, heavy transitive dependencies, or platform-specific constraints by placing them in named optional-dependency extras in pyproject.toml. This prevents adoption blockers for organizations with strict license policies while preserving full feature availability for users who opt in.

Why packages become optional#

Two recurring reasons motivate moving a package to an extra:

1. License risk. RapidOCR's transitive dependency on libopencv pulls in packages under GPL-2.0 (ffmpeg, x264, x265) and other restrictive licenses. Moving rapidocr out of core dependencies allows organizations that cannot accept these licenses to install Docling without them. 1
2. Missing or incomplete implementation. extract-msg (for Outlook .msg parsing) was added to the format-email extra only after the backend was actually implemented, so the feature doesn't ship as dead weight or with broken imports before it is ready. 2

Extra taxonomy#

Extras are grouped by function using consistent prefixes 3:

Two convenience bundles aggregate the most common combinations: standard (PDF + Office + email + RapidOCR + chunking + CLI) and all (everything) 4.

Note: The extract-msg package for Outlook .msg support was added to format-email in PR #3716. If it is not visible in the pyproject.toml snapshot above, check the live file — the snapshot reflects a specific commit.

OCR engine: graceful fallback#

Because OCR engines are optional, OcrAutoModel implements a runtime selection cascade rather than a hard import 5:

1. macOS: tries ocrmac first (platform-specific)
2. Linux: tries nemotron-ocr (platform- and hardware-gated)
3. All platforms: tries rapidocr with onnxruntime backend
4. All platforms: tries easyocr
5. All platforms: tries rapidocr with torch backend

Each step wraps the import in a try/except ImportError, so a missing package is logged and skipped rather than crashing. If no engine is found at all, the model logs a warning and yields pages through unchanged 6. Before PR #3248, rapidocr was a hard dependency, meaning this fallback was never reached in practice; making it optional exposed the cascade to users for the first time 1.

The same pattern applies to extract_msg in the email backend: the module is listed under allowed-unresolved-imports in the type-checker configuration so that import extract_msg can be guarded at runtime without causing type-check failures 2.

Installing optional extras#

# OCR support (recommended)
pip install 'docling[feat-ocr-rapidocr]'

# Outlook .msg email support
pip install 'docling[format-email]'

# Everything
pip install 'docling[all]'

Users migrating from earlier versions where rapidocr was a core dependency must now install it explicitly via pip install 'docling[feat-ocr-rapidocr]' 1.

Key files#

• pyproject.toml — canonical list of all extras and their version constraints
• docling/models/stages/ocr/auto_ocr_model.py — OCR engine auto-selection and graceful fallback logic
• docling/backend/email_backend.py — dual .eml/.msg parsing paths gated on optional extract_msg import