The docling program uses a thread pool to batch convert multiple docx files, but fails to convert several of them.

[ouyangyifan1231-oss]

Bug

When using docling to convert multiple docx files in a multithreaded environment, failure files may occur. However, for the same files, single-threaded conversion is always successful.

Steps to reproduce

Place 28 docx files in a folder and use the following program to convert them, set the number of threads to 4 or more, Then check the number of markdown files in the output folder, and you will find that some files have not been converted successfully.
Replacing the thread pool with a process pool will yield the same result.

import os
import subprocess
import concurrent.futures
import sys
from pathlib import Path

def convert_file(doc_path, output_dir=None):
    try:
        md_path = str(Path(doc_path).with_suffix('.md'))
        cmd = [
            "docling",
            "--image-export-mode", "referenced",
            "--from", "docx",
            "--to", "md",
            "--output", output_dir or os.path.dirname(md_path),
            doc_path
        ]
        subprocess.run(cmd, check=True, capture_output=True, text=True)
        print(f"✓ {os.path.basename(doc_path)}")
        return True
    except Exception as e:
        print(f"✗ {os.path.basename(doc_path)}: {e}")
        return False

def main():
    if len(sys.argv) < 2:
        print("用法: python script.py <文件夹路径> [输出路径] [线程数]")
        return

    folder = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else folder
    workers = int(sys.argv[3]) if len(sys.argv) > 3 else 4

    files = list(Path(folder).rglob("*.docx"))
    if not files:
        print("未找到docx文件")
        return

    print(f"找到 {len(files)} 个文件，开始转换...")

    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
        futures = {executor.submit(convert_file, str(f), output_dir): f for f in files}
        results = [future.result() for future in concurrent.futures.as_completed(futures)]

    success = sum(results)
    print(f"\n完成！成功: {success}, 失败: {len(results)-success}")

if __name__ == "__main__":
    main()

Docling version

docling-2.90.0

Python version

Python 3.12.12

[dosubot]

Hi @ouyangyifan1231-oss! I'm Dosu and I’m helping the docling team.

This is likely related to resource contention when multiple docling CLI processes run simultaneously. A few things to be aware of:

1. Docling has built-in parallel processing — rather than spawning multiple CLI subprocesses, you can use DocumentConverter.convert_all() with concurrency settings, which is the supported way to batch-convert [1]:

   from docling.document_converter import DocumentConverter
   from docling.datamodel.settings import settings
   
   settings.perf.doc_batch_concurrency = 4
   settings.perf.doc_batch_size = 4
   
   converter = DocumentConverter()
   for result in converter.convert_all(list_of_inputs):
       # export to markdown, etc.

2. Subprocess-based concurrency can hit issues — the CLI creates a single DocumentConverter per invocation [2], and running many of these simultaneously can cause problems with model loading/caching, memory accumulation from the underlying C++ docling-parse backend [3], and global lock contention on native libraries like pypdfium2 [4]. These issues can manifest as silent failures or crashes.

3. Thread oversubscription — when multiple docling processes each spawn their own internal threads (via PyTorch, ONNX Runtime, etc.), the system can become severely oversubscribed on CPU-only machines [5]. Setting OMP_NUM_THREADS=1 and DOCLING_NUM_THREADS=1 as environment variables before running can help if you're using external parallelism.

Recommendation: Switch to using convert_all() with the Python API instead of spawning multiple CLI subprocesses. This gives docling proper control over its internal parallelism and avoids the resource contention that's likely causing your failures. If you must use subprocess-based concurrency, try limiting workers to 2 and setting OMP_NUM_THREADS=1 to reduce contention.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[majestichou]

I encountered the same problem on Ubuntu 24.04 with docling-2.90.0, python 3.10.19