Native Library Compatibility#

Docling depends on three families of compiled (native) libraries, each with distinct compatibility concerns:

Platform detection governs which backends are selected at runtime. The environment is probed via sys.platform and platform.machine() in auto_ocr_model.py and auto_inline_engine.py, and platform metadata is stamped into every output document 1.

docling-parse: C++ Memory Accumulation#

The DoclingParseDocumentBackend (and its dlparse_v4 variant) hold internal C++ state that grows page-by-page across an entire conversion. Python's garbage collector cannot reclaim this memory. On large or image-heavy PDFs, this reliably triggers std::bad_alloc — typically around page 80 on an 80 MB, 184-page scanned document 2. The issue is tracked upstream in docling-parse#227 and docling#3345.

Three backends, three failure modes on the same large PDF 2:

The threaded_docling_parse backend has a release_native_memory_every_n_pages option (default: 128 pages) configured via ThreadedDoclingParseBackendOptions. ⚠️ Two caveats:

1. --release-native-memory-every-n-pages is silently ignored when used with any backend other than threaded_docling_parse 2.
2. threaded_docling_parse has a confirmed bug that silently drops tables (docling#3512) — do not use it in production where table accuracy matters.

Mitigations:

• CLI: --pdf-backend pypdfium2 — simplest workaround for scanned/OCR-dominated documents.
• Python API: Chunk by page range, creating a new DocumentConverter per chunk and calling del converter afterward to force the C++ backend to release memory 3.

pypdfium2: Thread Safety and Native Buffer Management#

pypdfium2 wraps libpdfium, a C library. All native operations are serialized through a global pypdfium2_lock (a threading.Lock) defined in locks.py. This lock is held across 15+ call sites in pypdfium2_backend.py: page geometry access, text cell computation, bitmap enumeration, image rendering, and page/document lifecycle.

Native buffer lifecycle: The get_page_image() method uses a copy-then-close pattern to avoid dangling references to native memory 4:

1. Render the page into a native bitmap.
2. Call bitmap.to_pil().copy() — copies pixel data into Python-managed memory.
3. Call bitmap.close() — releases the native buffer.
4. Release pypdfium2_lock, then resize the PIL image.

This ensures that the PIL image returned to Python never shares memory with the native bitmap.

API version compatibility: get_bitmap_rects() branches on the pypdfium2 version — obj.get_bounds() for v5.x+, obj.get_pos() for v4.x 5.

Termux / Android: On Android aarch64 (Termux), the linker emits warnings about libpdfium.so containing unknown processor-specific DT entries 6. These are non-fatal; pypdfium2 itself functions correctly on that platform.

ONNX Runtime: Version Constraints and PP-OCRv6 Incompatibility#

ONNX Runtime is used in three inference engine contexts: object detection (onnxruntime_engine.py), image classification (onnxruntime_engine.py), and RapidOCR 7.

Version ceilings (from pyproject.toml):

ONNX Runtime is not installed on Python 3.14+ due to these constraints.

PP-OCRv6 incompatibility: RapidOCR 3.9+ defaults to PP-OCRv6 model weights, but the torch inference backend does not support PP-OCRv6 — only the ONNX backend does 8. This produces:

ValueError: Unsupported configuration: torch.PP-OCRv6.det.small

The default RapidOcrOptions.backend is "onnxruntime" in code 9, so this error only appears when users or library code explicitly select the torch backend while running RapidOCR 3.9+.

Fixes 8:

• Switch to ONNX backend: RapidOcrOptions(backend="onnxruntime") + pip install onnxruntime
• Downgrade: pip install rapidocr==3.8.4 (intermediate workaround until upstream resolves this)

Platform-Specific Behavior#

OCR engine auto-selection :

Nemotron OCR is the most constrained native backend 12:

• Linux x86_64 only
• Python 3.12 exactly
• CUDA 13.x required
• Install: pip install "docling[feat-ocr-nemotron]"

The pyproject.toml dependency marker enforces this: python_version == "3.12" and sys_platform == "linux" and platform_machine == "x86_64" 13.

VLM inference engine selection 14: Darwin + MPS device → MLX engine; CUDA + prefer_vllm → vLLM; otherwise Transformers. The MLX engine serializes on a process-wide global lock because MLX is not thread-safe 15.

Termux / Android (non-standard platform): torchao 0.17.0+cpu causes a Bus error crash on Android aarch64 with kernel 4.14 and Python 3.14 — the native module csrc_meta_ops fails to load 6. torchao is not a Docling dependency and must have been installed externally. Fix: pip uninstall torchao. The root cause is a compiled binary incompatible with the older kernel, unrelated to Docling's own libraries.

Key Source Files#