Recursive AI

Publish a C# OCR app with Native AOT

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

Publish for Linux x64. The zip includes notice.png (“North entrance”).

Terminal
dotnet add package RecursiveAI.OneOcr

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

Install GCC and the zlib development headers first (on Ubuntu: sudo apt install gcc zlib1g-dev). To publish the example, run in its folder:

Terminal
dotnet publish -c Release -r linux-x64 \
  -p:PublishAot=true \
  -p:CppCompilerAndLinker=gcc
bin/Release/net10.0/linux-x64/publish/ocr

Unzip the example, then dotnet run.

Either run prints:

Text
North entrance

The full program

C#
using OneImage;
using OneOcr;
 
var engine = OcrEngine.LoadBundled();
var image = Image.Load("notice.png");
Console.WriteLine(image.ToText(engine));

See Microsoft’s Native AOT prerequisites for platform requirements. The default x64 build needs x86-64-v3 and refuses to start on older CPUs. The models are embedded in the executable; the input PNG stays separate.

Variations

Add this line after loading the engine, then publish again:

C#
Console.WriteLine(engine.KernelPath);
Text
Avx2
North entrance

Convert an image to text · Convert OCR to JSON · Share an OCR engine across workers


The short answer

Install RecursiveAI.OneOcr, load its bundled models with OcrEngine.LoadBundled(), then publish for the target platform with PublishAot=true. Native AOT compiles the application ahead of time. Use dotnet run to try the sample, but run the executable from publish/ to try the native build.

How do I publish an OCR library with .NET Native AOT?

Publish the console app that calls the library, not the library itself. The app in the zip uses Image.Load for pixels and ToText for the result. Neither operation needs a reflection-based JSON serializer. If you later need structured output, OneOcr’s own OcrPageJson writer uses Utf8JsonWriter to write its page format.

The publish command selects Linux x64 with -r linux-x64. This is a native binary for that target, not a portable DLL; choose a target that matches the system you intend to deploy to. The executable does not require a separately installed .NET runtime, but it can still depend on operating-system libraries, as noted in Microsoft’s Native AOT deployment overview.

Does my CPU support a Native AOT OCR executable built for AVX2?

For x64 publishes, RecursiveAI.OneOcr sets IlcInstructionSet to x86-64-v3 unless the app already chooses an instruction-set level. This lets the binary use AVX2 and FMA instructions. Check the deployment CPU, not just the build machine: a v3 binary won’t start on a CPU that lacks v3 support.

To target an x64 CPU that supports v2 but not v3, add -p:IlcInstructionSet=x86-64-v2 to the publish command. OneOcr uses its scalar kernel there; the recognized text is the same. The KernelPath variation reports what actually ran. The package’s x64 instruction-set setting does not apply to Arm.

Sources: OneOcr’s NativeAOT notes at v1.0.0 and the page JSON writer.

All oneocr recipes