---
title: "Publish a C# OCR app with Native AOT"
url: https://recursiveai.org/oneocr/cookbook/publish-local-ocr-with-native-aot/
description: "Publish a C# OCR app with .NET Native AOT for Linux x64. Run the native executable on a PNG with bundled models and no model download at startup."
version: "1.0.0"
---

# 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.

[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/publish-local-ocr-with-native-aot/publish-local-ocr-with-native-aot.zip)

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

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

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (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:

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

Unzip [the example](https://recursiveai.org/oneocr/cookbook/publish-local-ocr-with-native-aot/publish-local-ocr-with-native-aot.zip), then `dotnet run`.

Either run prints:

```text
North entrance
```

## The full program

```csharp
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](https://learn.microsoft.com/en-us/dotnet/core/deploying/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

### Print the OCR kernel in use

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

```csharp
Console.WriteLine(engine.KernelPath);
```

```text
Avx2
North entrance
```

## Related recipes

[Convert an image to text](https://recursiveai.org/oneocr/cookbook/extract-text-from-image/) · [Convert OCR to JSON](https://recursiveai.org/oneocr/cookbook/page-json/) · [Share an OCR engine across workers](https://recursiveai.org/oneocr/cookbook/reuse-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](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/).

## 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](https://github.com/recursive-ai-oss/oneocr-csharp/blob/8db430fb77c4d86d51686f15dfd9b5ccc20c99a7/README.md#L594-L612) and [the page JSON writer](https://github.com/recursive-ai-oss/oneocr-csharp/blob/8db430fb77c4d86d51686f15dfd9b5ccc20c99a7/src/OneOcr/PageModel/OcrPageJson.Write.cs#L66-L82).
