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:

| Family | OpenCV | .NET targets | Status | |---|---|---|---| | OpenCvSharp5 | 5.0.x | .NET 8+ | Active development — recommended for new projects | | OpenCvSharp4 | 4.13.0 | .NET Framework 4.6.1+, .NET Standard 2.0/2.1, .NET 8+ | Maintenance — for .NET Framework or older runtimes |

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

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 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 module set (videoio, dnn, ml, contrib, 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

Windows ARM64 (Snapdragon X Elite and other arm64 devices)

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)

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)

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 module set as the full Linux package (videoio, dnn, ml, contrib, 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.

• Enabled modules: core, imgproc, imgcodecs, calib3d, features2d, flann, objdetect, photo, ml, video, stitching, barcode
• Disabled modules: contrib, dnn, videoio, highgui

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

Usage

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

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

Documentation

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

| Package | Description | |---------|-------------| |OpenCvSharp5| OpenCvSharp core libraries | |OpenCvSharp5.GdipExtensions| GDI+ (System.Drawing) Extensions | |OpenCvSharp5.WpfExtensions| WPF Extensions | |OpenCvSharp5.AvaloniaExtensions| Avalonia Extensions (cross-platform) | |OpenCvSharp5.Windows| All-in-one package for Windows | |OpenCvSharp5.Windows.Slim| All-in-one slim package for Windows |

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

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

https://github.com/sponsors/shimat