shimat/opencvsharp

OpenCvSharp is a cross-platform .NET wrapper for OpenCV, providing a rich set of image processing and computer vision functionality. Its API is intentionally designed to stay as close as practical to the native OpenCV C++ API so that OpenCV concepts, documentation, and code can be transferred to .NET with minimal friction, while still using C# conventions such as typed enums, exceptions, and deterministic disposal.

See OpenCV C++, Python (cv2), and OpenCvSharp for the main API and data-model differences.

🚀 Try the Live Demo

Run OpenCvSharp image processing right in your browser — Blazor WebAssembly, no install needed.

Which version should I use?

OpenCvSharp is published in two parallel package families:

Both families share the same package layout: every OpenCvSharp5.* package has an OpenCvSharp4.* counterpart. The examples below use OpenCvSharp5; replace 5 with 4 for the OpenCvSharp4 family.

🔄 Already using OpenCvSharp4? See the Migration Guide (4 → 5) for target framework changes, package/namespace renames, and OpenCV 5 API changes.

Quick Start

Windows (x64)

dotnet add package OpenCvSharp5.Windows

Windows (ARM64 — Snapdragon X and other arm64 devices)

dotnet add package OpenCvSharp5
dotnet add package OpenCvSharp5.runtime.win-arm64

Linux / Ubuntu

dotnet add package OpenCvSharp5
dotnet add package OpenCvSharp5.official.runtime.linux-x64
# optional headless profile (full module set, no GTK3/X11 dependency)
# dotnet add package OpenCvSharp5.official.runtime.linux-x64.headless
# optional slim profile (smaller native dependency surface)
# dotnet add package OpenCvSharp5.official.runtime.linux-x64.slim
# ARM64 (AArch64): use OpenCvSharp5.official.runtime.linux-arm64 (.headless / .slim) instead

macOS

dotnet add package OpenCvSharp5
# Intel (x64):
dotnet add package OpenCvSharp5.runtime.osx.x64
# Apple Silicon (arm64):
dotnet add package OpenCvSharp5.runtime.osx.arm64

For more installation options, see the Installation section below, or the full NuGet package list.

Features

• OpenCvSharp is modeled on the native OpenCV C++ API as closely as practical.
• Many classes of OpenCvSharp implement IDisposable. Unsafe resources are managed automatically.
• OpenCvSharp does not force object-oriented programming style on you. You can also call native-style OpenCV functions.
• OpenCvSharp provides functions for converting from Mat to Bitmap (GDI+) or WriteableBitmap (WPF).

Target OpenCV

• OpenCvSharp5: OpenCV 5.0.x with opencv_contrib
• OpenCvSharp4: OpenCV 4.13.0 with opencv_contrib

Requirements

• OpenCvSharp5: .NET 8 or later
• OpenCvSharp4: .NET 8+, .NET Standard 2.0 / 2.1, or .NET Framework 4.6.1+ (WpfExtensions also directly targets .NET Framework 4.8)
• (Windows Server) Media Foundation

PS1> Install-WindowsFeature Server-Media-Foundation

• (Linux) The official OpenCvSharp5.official.runtime.linux-x64 package is built on manylinux_2_28 and works on Ubuntu 20.04+, Debian 10+, RHEL/AlmaLinux 8+, and other Linux distributions with glibc 2.28+. The full package includes FFmpeg (LGPL v2.1) and Tesseract statically linked. The OpenCvSharp5.official.runtime.linux-arm64 packages (full, headless, slim) are the ARM64 (AArch64) counterparts, built the same way on manylinux_2_28_aarch64.
  • The full package uses GTK3 for highgui support (Cv2.ImShow, Cv2.WaitKey, etc.). GTK3 is pre-installed on standard Ubuntu/Debian/RHEL environments. In minimal or container environments where it is absent, install it manually (apt-get install libgtk-3-0 or dnf install gtk3), or use the headless or slim profile instead.
  • The headless package (OpenCvSharp5.official.runtime.linux-x64.headless) keeps the full package's supported modules (videoio, dnn, ml, supported contrib bindings, stitching, barcode, ...) but disables highgui, so it has no GTK3/X11 dependency — suitable for containerized services that need more than the slim module set below.
  • The slim package (OpenCvSharp5.official.runtime.linux-x64.slim) disables highgui and reduces the module set — also has no GUI dependencies.

OpenCvSharp won't work on Unity and Xamarin platforms. For Unity, please consider using OpenCV for Unity or some other solutions.

OpenCvSharp does not support CUDA. If you want to use CUDA features, you need to customize the native bindings yourself.

OpenCV's OpenCL Transparent API can be used through UMat. See OpenCL Acceleration with UMat for runtime diagnostics and benchmarking guidance.

Installation

Windows x64

Add OpenCvSharp5 and OpenCvSharp5.runtime.win NuGet packages to your project. Alternatively, you can use the OpenCvSharp5.Windows all-in-one package. For a smaller feature profile, pair OpenCvSharp5 with OpenCvSharp5.runtime.win.slim, or use the all-in-one OpenCvSharp5.Windows.Slim package.

Windows ARM64 (Snapdragon X Elite and other arm64 devices)

Add OpenCvSharp5 and OpenCvSharp5.runtime.win-arm64 NuGet packages to your project. For a smaller feature profile, use OpenCvSharp5.runtime.win-arm64.slim instead.

Note: FFmpeg-based video I/O is not available in the ARM64 packages because no ARM64 Windows prebuilt is provided by the upstream OpenCV project. All other OpenCV modules are included in the full package.

Linux (Ubuntu and other distributions)

Add OpenCvSharp5 and OpenCvSharp5.official.runtime.linux-x64 NuGet packages to your project. This package uses the portable linux-x64 RID and works with .NET 8+ publish/deploy workflows out of the box. On ARM64 (AArch64), use OpenCvSharp5.official.runtime.linux-arm64 (or its .headless / .slim variants) instead.

dotnet new console -n ConsoleApp01
cd ConsoleApp01
dotnet add package OpenCvSharp5
dotnet add package OpenCvSharp5.official.runtime.linux-x64
# or headless profile (full module set, no GTK3/X11 dependency):
# dotnet add package OpenCvSharp5.official.runtime.linux-x64.headless
# or slim profile:
# dotnet add package OpenCvSharp5.official.runtime.linux-x64.slim
# -- edit Program.cs --- # 
dotnet run

macOS (Intel and Apple Silicon)

Add OpenCvSharp5 and the runtime package matching your architecture:

dotnet new console -n ConsoleApp01
cd ConsoleApp01
dotnet add package OpenCvSharp5
# Intel (x64):
dotnet add package OpenCvSharp5.runtime.osx.x64
# Apple Silicon (arm64):
dotnet add package OpenCvSharp5.runtime.osx.arm64
# --- edit Program.cs ---
dotnet run

Note: The macOS packages include FFmpeg, Tesseract, Freetype, and all standard OpenCV modules, statically linked.

Headless profile (Linux only)

OpenCvSharp5.official.runtime.linux-x64.headless keeps the same supported modules as the full Linux package (videoio, dnn, ml, supported contrib bindings, stitching, barcode, ...); only highgui is disabled, so the package has no GTK3/X11 dependency. Use it instead of the full package for containerized/headless services that need more than the slim module set below (e.g. VideoCapture) but never call highgui.

Slim profile module coverage

The slim runtime packages keep a practical subset while reducing runtime dependencies. They include geometry, calib, stereo, ptcloud, features, ml, and video as well as the basic image modules. Selected contrib bindings (bgsegm, img_hash, ximgproc, xphoto, xobjdetect, and BRISK/KAZE/AKAZE/AGAST from xfeatures2d) and ArUco APIs are available; dnn, videoio, highgui, stitching, and most contrib bindings are excluded.

See the OpenCV module coverage matrix for the full, headless, slim, and Android profiles and the limits of each check mark.

This profile is used by:

• OpenCvSharp5.runtime.win.slim
• OpenCvSharp5.Windows.Slim
• OpenCvSharp5.official.runtime.linux-x64.slim
• OpenCvSharp5.official.runtime.linux-arm64.slim

Usage

For step-by-step guides, package selection, and troubleshooting, see the OpenCvSharp documentation. More complete programs are available in the samples repository.

Always remember to release Mat and other IDisposable resources using the using syntax:

// Edge detection by Canny algorithm
using OpenCvSharp;

using var src = new Mat("lenna.png", ImreadModes.Grayscale);
using var dst = new Mat();

Cv2.Canny(src, dst, 50, 200);
using (new Window("src image", src))
using (new Window("dst image", dst))
{
    Cv2.WaitKey();
}

using var src = new Mat("lenna.png", ImreadModes.Grayscale);

// The intermediate (src * 0.8) holds no native resource; nothing leaks.
using Mat dst = 255 - src * 0.8;

using var mat1 = new Mat(new Size(100, 100), MatType.CV_8UC3, new Scalar(0));
using Mat mat3 = 255 - mat1 * 0.8;

using var canny = new Mat();
Cv2.Canny(src, canny, 50, 200);   // an expression can be passed directly to a Cv2 method

Code samples

https://github.com/shimat/opencvsharp_samples/

Interactive browser-based samples (Blazor WebAssembly) are maintained separately at https://github.com/shimat/opencvsharp_blazor_sample/, with a live demo.

Documentation

https://shimat.github.io/opencvsharp/

NuGet

Packages are published in two parallel families: OpenCvSharp5.* (OpenCV 5.x, .NET 8+) and OpenCvSharp4.* (OpenCV 4.13.0; also supports .NET Framework / .NET Standard). The tables below list the OpenCvSharp5 packages — each has an identically-named OpenCvSharp4.* counterpart.

Managed libraries

Native binding (OpenCvSharpExtern.dll / libOpenCvSharpExtern.so / libOpenCvSharpExtern.dylib) is required for OpenCvSharp to work. To use OpenCvSharp, you should add both OpenCvSharp5 and OpenCvSharp5.runtime.* packages to your project. Currently, native bindings for Windows x64/ARM64, Linux x64/ARM64, macOS x64/arm64, and WebAssembly are available.

Docker images

https://github.com/shimat?tab=packages

OpenCvSharp Build Instructions

If you want to build OpenCV and OpenCvSharp from source (Windows or Ubuntu), or customize a build for an embedded (ARM) platform, see Build Instructions.

Donations

If you find the OpenCvSharp library useful and would like to show your gratitude by donating, here are some donation options. Thank you.

https://github.com/sponsors/shimat