This page is generated. It is published automatically from doc/wiki/onnx-runtime-installation.md in the BirdNET-Go repository. Do not edit it here; changes are overwritten on the next sync. To propose a change, open a pull request against the source file.

ONNX Runtime is a shared library required by BirdNET-Go for neural network inference. It powers the BirdNET v2.4 classifier, Perch v2 embeddings, BattyBirdNET bat detection, range filtering, and BirdNET Geomodel features.

Note: ONNX Runtime will become the sole inference backend in a future release. TensorFlow Lite support is being phased out. If you are setting up a new installation, only ONNX Runtime is needed going forward.

Docker / container installs (install.sh): ONNX Runtime is baked into the container image. No action needed.

Release tarballs (.tar.gz from GitHub Releases): The ONNX Runtime library is bundled in every tarball. You just need to install it to the right location on your system. See the Installing from Release Tarballs section.

Building from source: You need to download ONNX Runtime yourself. See Manual Download.

BirdNET-Go requires ONNX Runtime 1.25.x. The Go bindings (onnxruntime_go) are compiled against ORT_API_VERSION 25, which only exists in the 1.25.x series. Older versions (1.24.x and below) and newer major versions will fail to load.

Every release tarball includes the ONNX Runtime library for the target platform. After extracting the archive, install the library to a system path so the dynamic linker can find it.

# Extract the tarball
tar xzf birdnet-go-linux-amd64-*.tar.gz

# Install the library system-wide
sudo cp libonnxruntime.so /usr/lib/
sudo ldconfig

# Verify
ldconfig -p | grep onnxruntime

Expected output:

libonnxruntime.so (libc6,x86-64) => /usr/lib/libonnxruntime.so

If you don't have root access, use LD_LIBRARY_PATH instead:

export LD_LIBRARY_PATH="$(pwd):$LD_LIBRARY_PATH"
./birdnet-go

Add the export to your ~/.bashrc or ~/.profile to make it persistent.

# Extract the tarball
tar xzf birdnet-go-darwin-arm64-*.tar.gz

# Install the library
sudo mkdir -p /usr/local/lib
sudo cp libonnxruntime.dylib /usr/local/lib/

# Remove quarantine attribute (macOS Gatekeeper)
xattr -d com.apple.quarantine /usr/local/lib/libonnxruntime.dylib

# Verify
ls -la /usr/local/lib/libonnxruntime.dylib

macOS does not use ldconfig. The dynamic linker searches /usr/local/lib/ by default.

If you prefer not to copy system-wide:

export DYLD_LIBRARY_PATH="$(pwd):$DYLD_LIBRARY_PATH"
./birdnet-go

Note: macOS System Integrity Protection strips DYLD_LIBRARY_PATH when launching through sudo or launchd. Use the /usr/local/lib/ method for service installations.

After extracting the archive, keep onnxruntime.dll in the same directory as birdnet-go.exe. Windows loads DLLs from the application directory automatically, so no additional installation is needed.

C:\BirdNET-Go\
  birdnet-go.exe
  onnxruntime.dll

If you want to run birdnet-go.exe from any directory, keep the DLL in a dedicated folder and add that folder to your user PATH. Avoid copying the DLL into C:\Windows\System32: that is a global, system-wide install that affects every application and is easy to get wrong.

# Example: keep onnxruntime.dll in C:\BirdNET-Go and add that folder to PATH
[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\BirdNET-Go", "User")

This updates your user PATH only and does not require Administrator privileges. Open a new terminal afterwards for the change to take effect.

If you are building from source or need to install ONNX Runtime separately, download it from the official Microsoft releases.

VERSION=1.25.1

curl -fsSL "https://github.com/microsoft/onnxruntime/releases/download/v${VERSION}/onnxruntime-linux-x64-${VERSION}.tgz" \
  -o onnxruntime.tgz

mkdir -p onnxruntime-tmp
tar xzf onnxruntime.tgz -C onnxruntime-tmp --strip-components=1
sudo cp onnxruntime-tmp/lib/libonnxruntime*.so* /usr/lib/
sudo ldconfig
rm -rf onnxruntime.tgz onnxruntime-tmp

VERSION=1.25.1

curl -fsSL "https://github.com/microsoft/onnxruntime/releases/download/v${VERSION}/onnxruntime-linux-aarch64-${VERSION}.tgz" \
  -o onnxruntime.tgz

mkdir -p onnxruntime-tmp
tar xzf onnxruntime.tgz -C onnxruntime-tmp --strip-components=1
sudo cp onnxruntime-tmp/lib/libonnxruntime*.so* /usr/lib/
sudo ldconfig
rm -rf onnxruntime.tgz onnxruntime-tmp

This covers Raspberry Pi 4/5 (64-bit OS), NVIDIA Jetson, and other ARM64 single-board computers.

VERSION=1.25.1

curl -fsSL "https://github.com/microsoft/onnxruntime/releases/download/v${VERSION}/onnxruntime-osx-arm64-${VERSION}.tgz" \
  -o onnxruntime.tgz

# Extract (BSD tar needs special handling)
mkdir -p onnxruntime-tmp
tar xzf onnxruntime.tgz -C onnxruntime-tmp
sudo cp -P onnxruntime-tmp/onnxruntime-*/lib/libonnxruntime*.dylib /usr/local/lib/
sudo xattr -d com.apple.quarantine /usr/local/lib/libonnxruntime*.dylib 2>/dev/null || true
rm -rf onnxruntime.tgz onnxruntime-tmp

For Intel Macs (x86_64), replace arm64 with x86_64 in the download URL:

VERSION=1.25.1

curl -fsSL "https://github.com/microsoft/onnxruntime/releases/download/v${VERSION}/onnxruntime-osx-x86_64-${VERSION}.tgz" \
  -o onnxruntime.tgz

Note: BirdNET-Go does not currently publish pre-built binaries for Intel Macs. You would need to build from source.

Download from a browser or PowerShell:

$VERSION = "1.25.1"

Invoke-WebRequest `
  -Uri "https://github.com/microsoft/onnxruntime/releases/download/v$VERSION/onnxruntime-win-x64-$VERSION.zip" `
  -OutFile onnxruntime.zip

Expand-Archive onnxruntime.zip -DestinationPath onnxruntime-tmp
Copy-Item onnxruntime-tmp\onnxruntime-*\lib\onnxruntime.dll -Destination .
Remove-Item -Recurse onnxruntime.zip, onnxruntime-tmp

Place onnxruntime.dll in the same directory as birdnet-go.exe.

If you have the BirdNET-Go source tree and Task installed:

task download-onnxruntime

This automatically detects your platform, downloads the correct archive, and installs the library to the appropriate system path. It requires sudo on Linux.

Platforms marked with "-" are not officially supported but may work with manual setup.

# Check the library is in the linker cache
ldconfig -p | grep onnxruntime

# Check the library version
readelf -d /usr/lib/libonnxruntime.so | grep SONAME

# Check the library exists
ls -la /usr/local/lib/libonnxruntime*.dylib

# Check the library can be loaded
otool -L /usr/local/lib/libonnxruntime.dylib

# Check the DLL exists alongside the binary
dir C:\BirdNET-Go\onnxruntime.dll

# Or check system-wide
where.exe onnxruntime.dll

When BirdNET-Go starts, it logs the ONNX Runtime version it loaded. Look for a line like:

ONNX Runtime initialized (version 1.25.1)

If the library is missing, you will see an error like:

error while loading shared libraries: libonnxruntime.so: cannot open shared object file

Linux: The library is not in the dynamic linker search path.

# Option 1: Install system-wide
sudo cp libonnxruntime.so /usr/lib/
sudo ldconfig

# Option 2: Set library path for current session
export LD_LIBRARY_PATH="/path/to/library:$LD_LIBRARY_PATH"

macOS: The library is not in /usr/local/lib/ or not in DYLD_LIBRARY_PATH.

sudo cp libonnxruntime.dylib /usr/local/lib/

If you get a Gatekeeper block, remove the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/lib/libonnxruntime.dylib

Windows: The DLL is not in the same directory as birdnet-go.exe and not in the system PATH.

Move onnxruntime.dll to the same folder as the executable.

If BirdNET-Go reports version incompatibility errors, download the exact version listed at the top of this guide (currently 1.25.1). Newer major versions may introduce breaking API changes.

Linux: Ensure the library file is readable:

sudo chmod 644 /usr/lib/libonnxruntime.so
sudo ldconfig

macOS: Same approach:

sudo chmod 644 /usr/local/lib/libonnxruntime.dylib

Use the Linux aarch64 package. Make sure you are running a 64-bit OS. The 32-bit (armhf) architecture is not supported by ONNX Runtime.

Check your architecture with:

uname -m
# Should show: aarch64

If it shows armv7l, you are running a 32-bit OS and need to switch to a 64-bit image (e.g., Raspberry Pi OS 64-bit).

• ONNX Runtime GitHub - official releases and documentation
• BirdNET-Go documentation
• BirdNET-Go GitHub - issues and discussions