How to Control Parallel OCR Memory Usage in C#

Why Does OCR Memory Grow During Large Batches?

When MultiThreaded is true, which is the default, IronOCR processes pages in parallel. Each concurrent page spins up its own native Tesseract engine holding image buffers, recognition models, and intermediate state in unmanaged memory.

Peak memory for a Read call therefore has two parts, and only one of them is under your control:

• A fixed cost for the document itself, which grows with the number of pages regardless of how they are scheduled.
• A marginal cost for each page read concurrently, one native engine apiece.

MaxDegreeOfParallelism acts on the second term only. That distinction matters: on a long document the fixed cost can be the larger share, so capping parallelism reduces peak memory substantially without ever driving it to zero.

In containerized environments - Docker with fixed --memory limits, Kubernetes pods with resource quotas - the marginal term is what turns a working job into an OOM kill, because it scales with the host's logical processor count rather than with anything you configured. On bare-metal servers it causes swapping and degrades throughput. We cap parallelism to keep the peak working set within a known budget.

How Much Memory Does Each Concurrent Page Use?

Measured against the reference workload below, those two terms come out as:

peak ≈ fixed document cost + (per-engine cost × concurrency)

Take the measured figures as a starting point and measure your own workload to refine them - both terms move with DPI, page complexity, document length, and language pack.

How Do I Cap How Many Pages Are Read at Once?

Set IronTesseract.MaxDegreeOfParallelism to the maximum number of pages that should process concurrently within a single Read call. Left alone, it defaults to Environment.ProcessorCount.

using IronOcr;
using System;

var ocr = new IronTesseract();

// Cap concurrency at 2 pages. Each concurrent page holds its own native
// engine, so this bounds peak memory for every Read on this instance.
ocr.MaxDegreeOfParallelism = 2;

// The cap applies per Read call, however many pages the document has.
using var input = new OcrInput();
input.LoadPdf("500-page-archive.pdf");

OcrResult result = ocr.Read(input);
Console.WriteLine(result.Text.Length);

using IronOcr;
using System;

var ocr = new IronTesseract();

// Cap concurrency at 2 pages. Each concurrent page holds its own native
// engine, so this bounds peak memory for every Read on this instance.
ocr.MaxDegreeOfParallelism = 2;

// The cap applies per Read call, however many pages the document has.
using var input = new OcrInput();
input.LoadPdf("500-page-archive.pdf");

OcrResult result = ocr.Read(input);
Console.WriteLine(result.Text.Length);

IRON VB CONVERTER ERROR developers@ironsoftware.com

How Do I Read Pages Sequentially?

Set MultiThreaded to false. This is the lowest-memory option, because only one native engine is ever active. The trade-off is throughput: a batch takes roughly N times longer than with N concurrent workers.

using IronOcr;

var ocr = new IronTesseract();

// One page at a time. Overrides MaxDegreeOfParallelism, whatever it is set to.
ocr.MultiThreaded = false;

using var input = new OcrInput();
input.LoadPdf("scans.pdf");

OcrResult result = ocr.Read(input);

using IronOcr;

var ocr = new IronTesseract();

// One page at a time. Overrides MaxDegreeOfParallelism, whatever it is set to.
ocr.MultiThreaded = false;

using var input = new OcrInput();
input.LoadPdf("scans.pdf");

OcrResult result = ocr.Read(input);

IRON VB CONVERTER ERROR developers@ironsoftware.com

How Do the Two Properties Interact?

Can I Bound Memory During Page Orientation Detection?

The new overload of OcrInput.DetectPageOrientation accepts a maxDegreeOfParallelism parameter that caps how many pages are orientation-detected concurrently. Non-positive values fall back to Environment.ProcessorCount. The single-argument overload is unchanged and remains source and binary compatible.

using IronOcr;
using System;

using var input = new OcrInput();
input.LoadPdf("rotated-scans.pdf");

// Analyse at most 2 pages at once. Orientation detection runs before the
// OCR read, so capping it here prevents a spike ahead of the real workload.
var results = input.DetectPageOrientation(
    OrientationDetectionMode.Fast,
    maxDegreeOfParallelism: 2);

// One result per page, in page order.
foreach (var result in results)
{
    Console.WriteLine($"Page {result.PageNumber}: {result.RotationAngle}");
}

using IronOcr;
using System;

using var input = new OcrInput();
input.LoadPdf("rotated-scans.pdf");

// Analyse at most 2 pages at once. Orientation detection runs before the
// OCR read, so capping it here prevents a spike ahead of the real workload.
var results = input.DetectPageOrientation(
    OrientationDetectionMode.Fast,
    maxDegreeOfParallelism: 2);

// One result per page, in page order.
foreach (var result in results)
{
    Console.WriteLine($"Page {result.PageNumber}: {result.RotationAngle}");
}

IRON VB CONVERTER ERROR developers@ironsoftware.com

Fast mode reuses one engine per worker thread instead of allocating one per page, which reduces peak memory further. This matters when orientation detection runs as a preprocessing step before the main OCR read, since capping parallelism here prevents a memory spike before the real workload begins.

Does Parallel OCR Still Crash on Large Batches?

Previous versions could throw a fatal AccessViolationException during parallel or high-volume OCR due to unsafe cross-thread access to native Tesseract state. That exception is unrecoverable - it terminates the process without a catch opportunity. It is now resolved. The previous workarounds, one IronTesseract instance per thread and one document at a time, are no longer necessary: the engine isolates native state per worker correctly, and MaxDegreeOfParallelism provides an official cap that replaces those ad-hoc patterns.

When Should I Tune These Settings?

• Container or CI runner with a memory cap - set MaxDegreeOfParallelism to keep peak memory within the limit.
• Batch processing thousands of pages - lower MaxDegreeOfParallelism to prevent OOM kills. Throughput decreases proportionally, but the job completes instead of crashing.
• Lowest possible memory - set MultiThreaded to false for sequential mode. One engine, one page at a time.
• Maximum throughput - leave both at their defaults so the engine uses all available cores. See the multithreading for speed example.
• Accuracy versus speed tuning - that is a different axis. The tune Tesseract for speed guide covers accuracy and speed trade-offs, while this page covers memory and throughput trade-offs.

For async and responsiveness concerns, such as keeping a UI responsive during OCR, see the async OCR how-to, which owns ReadAsync and OcrReadTask. This page covers resource bounding: keeping memory consumption predictable regardless of batch size.

Explore the IronTesseract configuration guide for the full property surface, loading PDF inputs and loading image inputs for OcrInput usage patterns, and page orientation detection for the DetectPageOrientation method and its new parallelism overload.

Explore IronOCR licensing options to move from trial to production.