Cross-Platform Support#

Docling officially supports macOS, Linux, and Windows on both x86_64 and arm64 architectures 1. A plain pip install docling works across all these targets; platform differences surface primarily in optional dependencies, OCR engine selection, and a small number of known runtime bugs.

Platform-Conditional Dependencies#

Platform markers in pyproject.toml enforce what gets installed per environment. Key cases:

macOS Intel (x86_64) requires pinning PyTorch to 2.2.2 because PyTorch 2.6+ dropped Intel Mac wheels. Install via pip install "docling[mac_intel]" or pin manually 8.

ONNX Runtime is not installed on Python 3.14+ on any platform due to hard version ceiling 9.

Runtime OCR Engine Selection#

OcrAutoModel uses a cascading try/except ImportError loop to select an OCR engine — no platform crashes if an engine is absent 10. Selection order:

1. macOS → OcrMacModel (Apple Vision)
2. Linux → NemotronOcrModel (if all constraints met)
3. All platforms → RapidOCR (ONNX) → EasyOCR → RapidOCR (torch)

Platform and architecture are probed at runtime via sys.platform and platform.machine() in auto_ocr_model.py and auto_inline_engine.py. Platform metadata (via platform.platform()) is also stamped into every output document's DoclingVersion record 11.

Container Images (docling-serve)#

docling-serve publishes hardware-targeted images on ghcr.io/docling-project/ 12:

All GPU-accelerated variants are AMD64-only 12.

Known Cross-Platform Bugs and Limitations#

Windows: Image path corruption in exports#

When using --image-export-mode referenced, image URIs are stored using OS-native path separators. On Windows, this produces %5C-encoded backslashes in HTML (<img src="...%5CfileName.png">) and literal backslashes in Markdown — both invalid in web contexts 13. Root cause: _with_pictures_refs() in docling_core/types/doc/document.py sets item.image.uri = Path(obj_path) without calling .as_posix(). A fix via docling-core PR #641 normalizes to forward slashes. Workaround until merged: patch document.py locally to use Path(obj_path).as_posix().

Windows / minimal containers: EPUB MIME type rejection#

DocumentOrigin.validate_mimetype falls back to the host's system MIME map. On Windows and slim Docker images, application/epub+zip is absent from the system map and is not in _extra_mimetypes in docling_core/types/doc/common/origin.py, causing both EPUB conversion and reloading saved EPUB documents to fail with a Pydantic ValidationError 14. Fix: add "application/epub+zip" to _extra_mimetypes.

macOS Intel: PyTorch compatibility#

PyTorch 2.6+ has no wheels for Intel Macs. Use pip install "docling[mac_intel]" which pins torch==2.2.2 and torchvision==0.17.2. Python must be ≤ 3.12 8.

ARM64 (Termux/Android, non-standard)#

On Android aarch64 (Termux), libpdfium.so emits linker warnings for unknown processor-specific DT entries — these are non-fatal 15. If torchao is installed externally, it may cause a Bus error on older kernels (4.14) with Python 3.14; fix with pip uninstall torchao 15.

Key References#