---
title: "Load a custom OCR recognition model in C#"
url: https://recursiveai.org/oneocr/cookbook/load-custom-ocr-recognition-model/
description: "Load an explicit OneOcr recognizer container in C#, add an optional detector, and handle model-format errors. Download and run a .NET 10 example."
version: "1.0.0"
---

# Load a custom OCR recognition model in C#

**OneOcr** is a free, open-source OCR library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneOcr) · [GitHub](https://github.com/recursive-ai-oss/oneocr-csharp) · [Docs](https://recursiveai.org/oneocr/docs/) · [Download example (.zip)](https://recursiveai.org/oneocr/cookbook/load-custom-ocr-recognition-model/load-custom-ocr-recognition-model.zip)

Load recognition weights from a file to use a fine-tuned OCR model. OneOcr accepts its `crnn-v0` model container (OneOcr’s own model file format), not arbitrary neural-network files.

```shell
dotnet add package RecursiveAI.OneOcr
dotnet add package RecursiveAI.OneOcr.Models
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using OneImage;
using OneOcr;

// recognizer.ocr: your fine-tuned model, or export the bundled
// starting weights with BundledModels.ReadRecognizer()
// (using OneOcr.Models;), as the full program does.
var engine = OcrEngine.Load(
    "recognizer.ocr",
    withBundledModels: false);
Console.WriteLine(engine.ToText(
    Image.Load("form.png")));
```

Unzip [the example](https://recursiveai.org/oneocr/cookbook/load-custom-ocr-recognition-model/load-custom-ocr-recognition-model.zip), then `dotnet run`.

Use your own `recognizer.ocr`; the full program exports the bundled starting recognizer if that file is absent. `form.png` is included. Prints:

```text
Invoice number: INV-1042
Date: 2026-11-16
Customer: Jane Smith
Total: 125.00
```

## The full program

The download includes `form.png`, an original synthetic form containing the four lines printed above.

No trained custom weights are included. This example exercises the file-loading API with the published starting weights. Replace `recognizer.ocr` with your fine-tuned container before running to use that model instead.

```csharp
using OneImage;
using OneOcr;
using OneOcr.Models;

// The demo exports the starting recognizer; use your fine-tuned file instead.
if (!File.Exists("recognizer.ocr"))
    File.WriteAllBytes("recognizer.ocr", BundledModels.ReadRecognizer());
var engine = OcrEngine.Load("recognizer.ocr", withBundledModels: false);
Console.WriteLine(engine.ToText(Image.Load("form.png")));

if (!BundledModels.TryReadDetector(out byte[] data, out string? reason))
    throw new InvalidOperationException(reason);
File.WriteAllBytes("detector.ocr", data);
var detected = engine.WithDetector("detector.ocr");
Console.WriteLine("With detector:");
Console.WriteLine(detected.ToText(Image.Load("form.png")));
try
{
    using var invalid = new MemoryStream(new byte[16]);
    OcrEngine.Load(invalid, withBundledModels: false);
}
catch (OcrModelException error)
{
    Console.WriteLine($"Bad model: {error.Message}");
}
```

```text
Invoice number: INV-1042
Date: 2026-11-16
Customer: Jane Smith
Total: 125.00
With detector:
Invoice number: INV-1042
Date: 2026-11-16
Customer: Jane Smith
Total: 125.00
Bad model: Not a model container: the magic bytes are wrong.
```

`Load` throws `OcrModelException` for malformed containers or the wrong architecture, and `OcrLimitException` when a model exceeds the configured limits.

## Variations

Load from a stream instead of a path. This replaces the first load and read in the program:

```csharp
using var model = File.OpenRead("recognizer.ocr");
var engine = OcrEngine.Load(model,
    withBundledModels: false);
Console.WriteLine(engine.ToText(
    Image.Load("form.png")));
```

```text
Invoice number: INV-1042
Date: 2026-11-16
Customer: Jane Smith
Total: 125.00
```

## Related recipes

- [Extract text from an image](https://recursiveai.org/oneocr/cookbook/extract-text-from-image/)
- [Read OCR words and coordinates as JSON](https://recursiveai.org/oneocr/cookbook/page-json/)

## The short answer

Call `OcrEngine.Load("recognizer.ocr", withBundledModels: false)` to load a recognizer alone, then call `engine.ToText(image)`. Add a detector with `WithDetector("detector.ocr")` when you want explicit page detection too. Neither operation requires setting `OcrEngine.Default`, so different callers can use different model instances.

On its first run it exports the package’s starting weights. When your own recognizer file is already present, the program leaves it in place and loads it.

## How do I load a custom OCR model in C#?

Use a OneOcr model container with the recognition architecture `crnn-v0`. The [Load API](https://github.com/recursive-ai-oss/oneocr-csharp/blob/8db430fb77c4d86d51686f15dfd9b5ccc20c99a7/src/OneOcr/OcrEngine.cs#L179-L208) accepts either a file path or a stream positioned at the start of that container. Loading weights is separate from choosing the image: load the engine first, then read each image using that engine.

The format is not inferred from a filename extension. Renaming another kind of model to `.ocr` does not convert its architecture or tensor layout. For your own weights, use the [training workflow](https://recursiveai.org/oneocr/docs/review-queue/) and the [model container specification](https://recursiveai.org/oneocr/docs/model-container/) rather than changing an unrelated file’s suffix.

### Does a custom recognizer need a page detector?

Not necessarily. With `withBundledModels: false`, the engine reads with the built-in classical line finder and no word model. The full program first runs in that configuration. It then loads an explicit detector file with `WithDetector` and reads the same image again. Both runs produce the printed form text in this example.

By default, `Load(path)` attaches bundled page models when available. That includes the page detector, word model and word frequencies. Merely supplying a recognizer path does not disable those additions. Pass `false` when you need recognition-only loading, and attach any detector you choose explicitly.

### Why does loading an OCR model fail?

A malformed container or a container describing another architecture raises `OcrModelException`. The program demonstrates the malformed case with a short stream of zero bytes; the exact message is shown above. A model beyond the configured resource bounds raises `OcrLimitException` instead. A missing path is a file-access problem, not evidence that the weights are compatible.

Keep recognition weights distinct from document extraction weights. Recognition reads letters from the image. A document extractor consumes recognized words and assigns fields or key/value relationships. An extraction model is therefore not an interchangeable input to `OcrEngine.Load`. Use the appropriate loader for each role rather than trying loaders until one accepts a file.

For an application with several models, retain explicit engine references and pass the intended one to each read. This avoids changing a process-wide default simply to handle one document with another recognizer.
