Docling Resource Requirements#

Overview#

Docling has no published minimum hardware specification. Resource needs vary substantially by pipeline mode (standard vs. VLM), document type (scanned/OCR-heavy vs. native-text PDF), and the number of concurrent workers. The four resource axes to size are:

GPU acceleration provides up to 6× speedup compared to CPU-only processing and is essential for production-throughput workloads 1. CPU-only is viable for low-volume or development use.

Related articles: Large PDF Memory Management · GPU Memory Management in docling-serve · GPU Accelerator Support · Container Image Variants

GPU VRAM#

Batch size is the primary VRAM lever — it has zero effect on throughput but dramatically increases memory usage. Empirically, the default batch size of 4 consumes ~1.6 GB VRAM, while batch size 256 consumes ~21 GB for the same throughput 2.

Docling's official guidance maps VRAM to safe batch size ranges 3:

Default batch sizes for layout, OCR, and table processing are all 4 4. table_batch_size currently does not use GPU batching 5. OCR GPU acceleration is only confirmed with RapidOCR using the torch backend.

4 GB GPUs are marginal. Users with 4 GB VRAM have encountered CUDA OOM errors (CUDNN_STATUS_EXECUTION_FAILED_CUDART, cublasCreate failures) even after reducing to --num-threads 1 --page-batch-size 1 2.

Multi-worker VRAM multiplication: In docling-serve's local orchestrator, each worker loads its own model copies by default. With 2 workers (the default), VRAM usage doubles. Set DOCLING_SERVE_ENG_LOC_SHARE_MODELS=true to share models across workers 6.

Troubleshooting CUDA OOM: reduce batch sizes in pipeline_options, process fewer documents concurrently, and clear the GPU cache between batches with torch.cuda.empty_cache() 7. See the OOM Failure Modes and Mitigations section for the full checklist.

System RAM#

No official minimum RAM requirement is published. Practical failure reports provide the clearest sizing signal:

• 16 GB RAM (AMD Ryzen 5, Windows 11): std::bad_alloc errors starting at page 13 on a 184-page scanned PDF 8
• 16 GB RAM (Windows 11): hour-long CPU run on the same 184-page 80 MB scanned PDF ultimately failed due to C++ memory exhaustion 2

The root cause is the docling-parse C++ backend, which accumulates native memory page-by-page and cannot be reclaimed by Python's garbage collector 9. Image-heavy and scanned PDFs grow memory faster than native-text PDFs because each page requires larger rasterized image buffers.

Reference benchmark infrastructure from the official GPU performance tests: the g6e.2xlarge (AWS L40S) and RTX 5070 machines each used 64 GB RAM; the RTX 5090 machine used 128 GB RAM 10. These are not minimum requirements but indicate the scale of hardware used for production benchmarking.

For docling-serve Ray deployments, per-actor memory budgets can be set via DOCLING_SERVE_ENG_RAY_CONVERTER_ACTOR_MEMORY_REQUEST (e.g., "4Gi"); the default is uncapped 6.

Disk Space (Model Storage)#

Model artifacts are required only for PDF processing. Other formats (DOCX, PPTX, images, HTML, etc.) do not need model weights.

Container image sizes 11:

All official images bake in the default model set at build time (layout, tableformer, picture_classifier, rapidocr, easyocr) to DOCLING_SERVE_ARTIFACTS_PATH=/opt/app-root/src/.cache/docling/models, eliminating cold-start downloads 11.

For standalone Python installs, models are downloaded on-demand from the ds4sd/docling-models Hugging Face repository to the user's local cache.

Kubernetes: The reference PVC for a model cache requests 10 GB storage 12. This covers the default model set with headroom for additional model variants.

CPU and Threading#

CPU thread count is controlled by DOCLING_NUM_THREADS (or OMP_NUM_THREADS as a fallback), with a default of 4 13. Official containers set OMP_NUM_THREADS=4 to limit OpenMP parallelism and associated memory overhead 11.

Throughput comparison from official benchmarks 14:

CPU-only inference runs 5–6× slower than GPU. For CPU-only deployments, increasing thread count (num_threads=8 or higher) on multi-core servers improves throughput.

For docling-serve Ray deployments, the default CPU allocation is 1.0 CPU per converter actor and 0.25 CPU per coordinator/dispatcher actor 6.

All official container images preload mimalloc (v3.2.8) via LD_PRELOAD to reduce heap fragmentation and lower resident memory 6.

OOM Failure Modes and Mitigations#

std::bad_alloc (C++ backend RAM exhaustion)#

The docling_parse (default) and dlparse_v4 backends accumulate C++ native memory across pages. When RAM is exhausted, you get visible errors in the pipeline log:

ERROR docling.pipeline.standard_pdf_pipeline: Stage preprocess failed for run 1, pages [13]: std::bad_alloc

8 2

Mitigations:

• Switch to --pdf-backend pypdfium2 — avoids C++ accumulation entirely; trade-off is lower table cell quality 9
• Use page-range batching via the Python API: create a new DocumentConverter per batch and call del converter to force C++ memory release 9
• The threaded_docling_parse backend's --release-native-memory-every-n-pages option can help but has a known bug silently dropping tables and is ignored when used with any other backend 9

CUDA OOM (VRAM exhaustion)#

Symptoms: RuntimeError: cuDNN error: CUDNN_STATUS_EXECUTION_FAILED_CUDART or cublasCreate failure.

Mitigations 7:

1. Reduce layout_batch_size, ocr_batch_size in pipeline_options
2. Process fewer documents concurrently
3. Call torch.cuda.empty_cache() between batches
4. Enable model sharing: DOCLING_SERVE_ENG_LOC_SHARE_MODELS=true

Silent failure (threaded backend)#

threaded_docling_parse can produce 0-byte output files while logging success, or silently drop tables. This is a known data-loss bug, not a transient error 9. Do not use this backend in production if table extraction accuracy matters.

Monitoring (docling-serve)#

Enable management endpoints (DOCLING_SERVE_ENABLE_MANAGEMENT_ENDPOINTS=true) to access:

• GET /v1/memory/stats — process RSS and cgroup memory breakdown
• GET /v1/memory/counts — GC stats and top object types by count

6

Ray deployments include built-in OOM protection (DOCLING_SERVE_ENG_RAY_ENABLE_OOM_PROTECTION=true by default), which triggers warnings at 90% memory utilization 6.