---
title: "Load ONNX external weights in C#"
url: https://recursiveai.org/onemodel/cookbook/load-onnx-external-weight-files/
description: "Load an ONNX model and its separate weight files in C#. See how OneModel finds external data from a file path or a stream and what happens when it is missing."
version: "1.3.0"
---

# Load ONNX external weights in C#

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

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneModel) · [GitHub](https://github.com/recursive-ai-oss/onemodel-csharp) · [Docs](https://recursiveai.org/onemodel/docs/) · [Download example (.zip)](https://recursiveai.org/onemodel/cookbook/load-onnx-external-weight-files/load-onnx-external-weight-files.zip)

Load `scale.onnx` from the zip. OneModel finds `data/scale.weights` relative to the model file.

```shell
dotnet add package RecursiveAI.OneModel
```

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

```csharp
using RecursiveAI.OneModel;

using var model = Model.Load("scale.onnx");
float[] input = [2];
float[] output = model.Run(input, [1]);
Console.WriteLine(output[0]);
```

Unzip [the example](https://recursiveai.org/onemodel/cookbook/load-onnx-external-weight-files/load-onnx-external-weight-files.zip), then `dotnet run`.

The sample multiplies the input by the stored weight `3`:

```text
6
```

## The full program

`scale.onnx` contains one `Mul` node: `y = x * w`. This is the weight reference in the model (decoded from ONNX’s binary format):

```text
w: float32[1], data_location = EXTERNAL
location = data/scale.weights
offset = 4
length = 4
```

`data/scale.weights` contains `00 00 00 00 00 00 40 40` in hex. The model skips the first four bytes and reads the second four as a little-endian float32, `3`.

```csharp
using RecursiveAI.OneModel;
using RecursiveAI.OneModel.Onnx;

const string path = "scale.onnx";
using (var model = Model.Load(path))
    Console.WriteLine($"Path: {model.Run(new float[] { 2 }, [1])[0]}");

var options = new ModelLoadOptions
{
    ExternalDataDirectory = Path.GetDirectoryName(Path.GetFullPath(path))!
};
using (var stream = File.OpenRead(path))
using (var model = Model.Load(stream, loadOptions: options))
    Console.WriteLine($"Stream: {model.Run(new float[] { 2 }, [1])[0]}");

try
{
    using var stream = File.OpenRead(path);
    using var model = Model.Load(stream);
}
catch (OnnxImportException error)
{
    Console.WriteLine($"Stream without directory: {error.Kind}");
}
```

```text
Path: 6
Stream: 6
Stream without directory: ExternalData
```

If `data/scale.weights` is missing, the path load throws `OnnxImportException` with kind `ExternalData` and names the missing file.

## Variations

**Load model bytes from memory, with weights on disk.** Use the model’s folder as the base directory. If you’re running from another folder, pass the path to `scale.onnx` after `dotnet run --`.

```csharp
using RecursiveAI.OneModel;

string path = Path.GetFullPath(
    args.Length == 0 ? "scale.onnx" : args[0]);
byte[] bytes = File.ReadAllBytes(path);
var options = new ModelLoadOptions
{
    ExternalDataDirectory = Path.GetDirectoryName(path)!
};
using var model = Model.Load(bytes, loadOptions: options);
float[] input = [2];
Console.WriteLine(model.Run(input, [1])[0]);
```

```text
6
```

## Related recipes

- [Run an ONNX model in C#](https://recursiveai.org/onemodel/cookbook/run-onnx-model/)
- [Convert an ONNX model to OneModel format](https://recursiveai.org/onemodel/cookbook/convert-to-onemodel-format/)

## The short answer

If you have a local `.onnx` file, pass its path to `Model.Load` and keep each weight file where the model expects it. If you pass a stream or bytes instead, supply `ModelLoadOptions.ExternalDataDirectory`. This is the base directory for the relative paths in the model, not the path to a particular weight file.

## What is ONNX external data?

[ONNX external data](https://onnx.ai/onnx/repo-docs/ExternalData.html#tensorproto-data-location-and-external-data-fields) lets a tensor store its values outside the `.onnx` file. The tensor’s name, shape, and type are still part of the model, but `location` points to the file with its values. Several tensors can point to different byte ranges in the same file. `offset` starts at zero if omitted; in OneModel, an omitted `length` means the expected byte count for that tensor.

A single serialized ONNX protobuf has a size limit below 2 GiB. A separate weight file can exceed that limit: OneModel checks offsets and lengths in 64 bits and addresses each tensor separately. That’s a per-file distinction, not a promise that any individual tensor fits. See [OneModel’s ONNX import guide](https://recursiveai.org/onemodel/docs/onnx-import/#large-files).

## How do you load an ONNX model with external data from a stream?

Pick the directory that contains the weight files in their original layout. For the example, that’s the folder containing `scale.onnx`, not its `data` subfolder: the relative reference already starts with `data/`. Pass that directory in `loadOptions` when opening the stream. OneModel doesn’t infer it even if you supply a `FileStream` that you opened from a local path. A stream containing only the model still needs its external weights on disk.

## Why can’t the loader find an ONNX weight file?

Check the model’s `location` against what you deployed. Copying only the `.onnx` file isn’t enough. If `location` is `data/scale.weights`, placing the weights beside `scale.onnx` or renaming the file breaks the reference. Move both files together and preserve the subdirectory. For a stream or bytes, check `ExternalDataDirectory` first: without it there’s no base for the lookup.

OneModel also rejects absolute locations, `..` path components, and links that resolve outside the base directory. If the file exists but loading still fails, check whether the byte range fits inside the file. If the model specifies a length, it must match the tensor’s expected size. A truncated weight file can fail even when its name is correct. See [the external data rules](https://recursiveai.org/onemodel/docs/onnx-import/#5-external-data).
