Large PDF Memory Management#

Processing large or multi-page PDFs in Docling can exhaust system memory due to how the C++ docling-parse backend accumulates native memory across pages, bypassing Python's per-page cleanup. This can surface as std::bad_alloc errors mid-conversion or — with the threaded backend — as silent failures with zero output 1. The issue is documented in docling-parse#227 and docling#3345.

Root Cause#

The DoclingParseDocumentBackend (default: docling_parse) holds internal C++ state that grows page-by-page and is not released between pipeline stages. For scanned/image-heavy PDFs, this grows rapidly: a 184-page scanned grayscale PDF reliably triggers std::bad_alloc starting around page 80+ 1. Python GC cannot reclaim this memory; releasing it requires explicit action at the C++ level.

PDF Backend Options and Trade-offs#

Docling supports multiple backends, selected via pdf_backend in pipeline options or --pdf-backend on the CLI 2:

Mitigation Strategies#

1. Switch to pypdfium2 (simplest CLI workaround)#

For scanned/OCR-heavy documents where native text extraction quality is less important, pypdfium2 avoids C++ memory accumulation entirely. The main trade-off is table cell quality: pypdfium2 produces fragmented sub-word cells vs. the cleaner hierarchical cells from docling-parse 1.

docling --pdf-backend pypdfium2 large_doc.pdf

2. Use threaded_docling_parse with periodic memory release ⚠️#

The ThreadedDoclingParseDocumentBackend supports the release_native_memory_every_n_pages option, which triggers a C++ memory flush after every N pages 3. It is configured via ThreadedDoclingParseBackendOptions:

• Default: 128 pages
• Range: any integer ≥ 0; set to 0 to disable
• Python API: ThreadedDoclingParseBackendOptions(release_native_memory_every_n_pages=20)
• CLI: --release-native-memory-every-n-pages 20 (only when --pdf-backend threaded_docling_parse)

⚠️ Known bug: ThreadedDoclingParseDocumentBackend silently drops tables that the serial backend detects. This reproduces even at parser_threads=1, so it is not a concurrency issue — the threaded backend feeds different cell/layout data into the table-structure stage 4. Do not use this backend in production if table extraction accuracy is required.

⚠️ --release-native-memory-every-n-pages is silently ignored when used with any backend other than threaded_docling_parse 1 5.

Additional CLI levers to reduce peak memory when using the threaded backend:

• --num-threads 1 (default 4)
• --page-batch-size 1 (default 4)

3. Page-range batching via Python API (most reliable)#

Process a large document in chunks by passing page_range=(start, end) to DocumentConverter.convert() 6. Critically, create a new DocumentConverter instance per batch and call del converter afterward to force the C++ backend to release memory 1:

from docling.document_converter import DocumentConverter

results = []
for start in range(1, total_pages, chunk_size):
    converter = DocumentConverter()
    result = converter.convert(path, page_range=(start, start + chunk_size - 1))
    results.append(result)
    del converter # forces C++ memory release

The page_range parameter is defined in DocumentLimits and flows through convert() → convert_all() → InputDocument.limits → backend 6. There is no --page-range flag on the local CLI docling convert command (it exists only for convert-remote) 1.

⚠️ Tables that span a batch boundary will be split across chunks.

Key Source Files#

Open Issues#

• docling#3671 — std::bad_alloc on large scanned PDFs; covers all three failure modes 1
• docling#3512 — ThreadedDoclingParseDocumentBackend silently drops tables 4
• docling#3345 — Original OOM bug report; introduced threaded backend as mitigation 7
• docling-parse#227 — Upstream C++ memory accumulation tracking issue