Setting pypdfium2 as backend.

[jacknguyen0810]

Question

I am trying to improve the speed of the processing, so I want to use pypdfium2 as the backend.

What prerequisite steps are needed to do this?
What are the methods for doing this?

Thanks.

[dosubot]

To use pypdfium2 as the backend in Docling, just install Docling (it includes pypdfium2), then configure your pipeline to use the PyPdfiumDocumentBackend. In Python, import it with:

from docling.backend.pypdfium2_backend import PyPdfiumDocumentBackend
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions

pipeline_options = PdfPipelineOptions(
    images_scale=1.0,
    generate_page_images=False,
    generate_picture_images=False,
    do_formula_enrichment=False,
    # add other options as needed
)

doc_converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=pipeline_options,
            backend=PyPdfiumDocumentBackend
        )
    }
)

This setup maximizes speed by skipping expensive image and formula extraction steps. For even faster processing, use the ThreadedStandardPdfPipeline for parallelism and set AcceleratorOptions to match your CPU cores if you want to batch pages [docs/examples/custom_convert.py] [docs/v2.md].

If you prefer the CLI, use:

docling convert input.pdf output.json --pdf-backend pypdfium2 --images-scale 1.0 --generate-page-images false --generate-picture-images false

(Backend selection via CLI is deprecated in v2, so use the Python API for new projects.)

Switching to pypdfium2 resolves memory and speed issues seen with the default backend, especially for large or complex PDFs [source]. The backend is thread-safe and stable for production [source].

For more details and examples, check out the custom_convert.py example and v2 documentation.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[jacknguyen0810]

Can you expand on CPU threading?

[dosubot]

Docling uses a multi-threaded pipeline to speed up PDF processing, including when using the pypdfium2 backend. Each stage of the pipeline (like OCR, layout, table extraction) runs in its own thread, and pages are processed in batches to maximize throughput. You can control threading and batching with these options:

• Set the number of CPU threads and device type using AcceleratorOptions(num_threads=..., device='cpu'). You can also use environment variables like DOCLING_NUM_THREADS or OMP_NUM_THREADS to set thread count.
• Tune batch sizes for each stage (OCR, layout, table) using ThreadedPdfPipelineOptions (e.g., ocr_batch_size, layout_batch_size, table_batch_size). Start with 4–16 pages per batch and adjust based on your hardware and workload.
• In the CLI, use flags like --page-batch-size to control batching, or set environment variables (e.g., DOCLING_SERVE_OCR_BATCH_SIZE) in Docling Serve for parallel page processing.

Example for Python:

from docling.datamodel.pipeline_options import ThreadedPdfPipelineOptions, AcceleratorOptions
from docling.backend.pypdfium2_backend import PyPdfiumDocumentBackend
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat

pipeline_options = ThreadedPdfPipelineOptions(
    ocr_batch_size=8,
    layout_batch_size=8,
    table_batch_size=4,
    accelerator_options=AcceleratorOptions(num_threads=8, device='cpu'),
    # ...other options...
)

doc_converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=pipeline_options,
            backend=PyPdfiumDocumentBackend
        )
    }
)

The pipeline is designed for thread safety and high throughput, but true parallelism may be limited by Python's GIL and global locks in native libraries like pypdfium2. For very high concurrency or CPU-bound workloads, consider using process pools (multiprocessing) instead of threads. Always create a new DocumentConverter per process and avoid sharing instances across threads or processes to prevent crashes or memory issues. Recent Docling versions have improved thread safety, but running the latest release is recommended for stability [source] [source] [source].

For more details and example scripts, see the run_with_accelerator.py example.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[jacknguyen0810]

For my current format, I am using PdfPipelineOptions to control parameters such as artifacts path, image_scale, ... etc. I am also creating a single DocumentConvrter and then calling it every time to process a document, as I pass it a single document at a time. What changes would be needed to make use of CPU threading (for 2 cpus for example)?

[dosubot]

To use CPU threading with 2 CPUs in Docling, switch from PdfPipelineOptions to ThreadedPdfPipelineOptions, which adds batching and concurrency controls. Set accelerator_options to use 2 threads and the CPU device. Your usage pattern—creating a single DocumentConverter and calling it for each document sequentially—is compatible with threading, as long as you don't share the instance across threads or processes.

Here's how you can update your setup:

from docling.datamodel.pipeline_options import ThreadedPdfPipelineOptions, AcceleratorOptions, AcceleratorDevice
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.backend.pypdfium2_backend import PyPdfiumDocumentBackend

pipeline_options = ThreadedPdfPipelineOptions(
    artifacts_path="your_artifacts_path",
    images_scale=1.0,
    generate_page_images=False,
    generate_picture_images=False,
    accelerator_options=AcceleratorOptions(
        num_threads=2, 
        device=AcceleratorDevice.CPU
    ),
    ocr_batch_size=4,
    layout_batch_size=4,
    table_batch_size=4,
    pdf_backend="pypdfium2"
)

doc_converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=pipeline_options,
            backend=PyPdfiumDocumentBackend
        )
    }
)

You can keep reusing this doc_converter for sequential document processing. If you want to process multiple documents in parallel (e.g., with ThreadPoolExecutor or ProcessPoolExecutor), create a separate DocumentConverter per thread or process to avoid crashes and race conditions [source].

Best practices: tune batch sizes and thread count for your hardware, disable non-essential features for speed, and use the pypdfium2 backend for fastest parsing. True parallelism is limited by Python's GIL and global locks in PDF backends, so for heavy workloads, process-based parallelism is safer [source].

If you only want to set the number of threads for internal model inference (not full pipeline threading), you can just set accelerator_options in PdfPipelineOptions, but for full concurrency, use ThreadedPdfPipelineOptions [source].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[jacknguyen0810]

@dosu I am running this package in a notebook. What if I only know that I have 2 vCores on CPU, how would I best set the settings? I am not also using ThreadPoolExecutor, do I need to?

[dosubot]

You don't need to use ThreadPoolExecutor for your notebook setup if you're processing one document at a time—Docling's internal threading will handle parallelism within each document for you. For your 2 vCores, set up your pipeline like this:

from docling.datamodel.pipeline_options import ThreadedPdfPipelineOptions, AcceleratorOptions, AcceleratorDevice
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.backend.pypdfium2_backend import PyPdfiumDocumentBackend

pipeline_options = ThreadedPdfPipelineOptions(
    artifacts_path="your_artifacts_path",
    images_scale=1.0,
    generate_page_images=False,
    generate_picture_images=False,
    accelerator_options=AcceleratorOptions(
        num_threads=2, 
        device=AcceleratorDevice.CPU
    ),
    ocr_batch_size=4,
    layout_batch_size=4,
    table_batch_size=4,
    pdf_backend="pypdfium2"
)

doc_converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=pipeline_options,
            backend=PyPdfiumDocumentBackend
        )
    }
)

This config uses both CPU cores efficiently and disables non-essential features for speed. You can keep reusing this doc_converter for sequential processing in your notebook. If you ever want to process multiple documents in parallel, then you'd need to use ThreadPoolExecutor or ProcessPoolExecutor and create a separate DocumentConverter per worker, but that's not needed for your current workflow.

No notebook-specific caveats—just tune batch sizes if you notice bottlenecks, and keep Docling up to date for best thread safety and performance. If you hit any memory or stability issues, consider lowering batch sizes or processing especially large PDFs in smaller chunks.
Sources:

• Threading and batch settings for 2 vCores
• Threaded pipeline options and best practices
• ThreadPoolExecutor not required for sequential processing

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}