OpenCvSharpExtern が見つからない（DllNotFoundException）の解決方法【C#】

OpenCvSharp を使い始めたとき、最初に遭遇しやすいのがこのエラーです。プログラムを実行した瞬間に例外が飛んで、画像の一枚も表示できないまま詰まってしまいます。原因はほぼパターンが決まっており、正しく対処すれば短時間で解決できます。

発生するエラーメッセージ

Unhandled exception. System.DllNotFoundException:
  Unable to load DLL 'OpenCvSharpExtern' or one of its dependencies.
  (0x8007007E)

または

System.TypeInitializationException: The type initializer for 'OpenCvSharp.NativeMethods'
threw an exception.
 ---> System.DllNotFoundException: Unable to load DLL 'OpenCvSharpExtern'

TypeInitializationException でラップされるケースも多く、内側の DllNotFoundException を見落としやすいので注意してください。

---

原因

原因1: OpenCvSharp4.runtime.win が入っていない

最頻出の原因です。OpenCvSharp は マネージドラッパー（OpenCvSharp4） と ネイティブバイナリ（OpenCvSharp4.runtime.win） の2パッケージがセットで必要です。ラッパーだけインストールして動かそうとすると、ネイティブDLL OpenCvSharpExtern.dll が存在しないためこのエラーになります。

// 必要な NuGet パッケージ（2つセットで入れる）
OpenCvSharp4
OpenCvSharp4.runtime.win   ← これが抜けているとエラーになる

原因2: ターゲットフレームワーク・プラットフォームの不一致

OpenCvSharp4.runtime.win のネイティブDLLは x64 / x86 それぞれ別ビルドです。プロジェクトのプラットフォームターゲットが Any CPU のままで「32ビットを優先する」チェックが入っている場合や、x86 専用で動かしているのに x64 ビルドのDLLしかない場合に不一致が起きます。

原因3: 出力ディレクトリにDLLがコピーされていない

NuGet で正しくインストールしたはずなのに実行ディレクトリに OpenCvSharpExtern.dll が見当たらない、というケースです。csproj の設定や NuGet のキャッシュ破損によってファイルがコピーされないことがあります。

---

解決方法

解決1: NuGetパッケージを2つセットで追加する

Package Manager Console で次を実行します。

Install-Package OpenCvSharp4
Install-Package OpenCvSharp4.runtime.win

dotnet CLI の場合は次のとおりです。

dotnet add package OpenCvSharp4
dotnet add package OpenCvSharp4.runtime.win

インストール後、csproj に以下のように両方が含まれていることを確認してください。

<PackageReference Include="OpenCvSharp4" Version="4.*" />
<PackageReference Include="OpenCvSharp4.runtime.win" Version="4.*" />

解決2: 出力ディレクトリにDLLが存在するか確認する

ビルド後、bin\Debug\net8.0\ などの出力ディレクトリを開き、OpenCvSharpExtern.dll があるかを確認します。

bin\Debug\net8.0\
├── MyApp.exe
├── OpenCvSharp.dll
├── OpenCvSharpExtern.dll   ← これが必要
└── ...

存在しない場合は、NuGet キャッシュをクリアして再ビルドします。

dotnet nuget locals all --clear
dotnet restore
dotnet build

解決3: プラットフォームターゲットを明示する

csproj に <PlatformTarget> を明示的に指定します。多くの環境では x64 が安全です。

<PropertyGroup>
  <PlatformTarget>x64</PlatformTarget>
</PropertyGroup>

Visual Studio を使う場合は「プロジェクトのプロパティ」→「ビルド」→「プラットフォームターゲット」で x64 を選択します。

動作確認用の最小コード

環境が正しく整っているかを確認するための最小プログラムです。

// NuGet: OpenCvSharp4 + OpenCvSharp4.runtime.win（Windows実行時）
using OpenCvSharp;

// 動作確認: 100x100 の白画像を生成して保存する
using var mat = new Mat(100, 100, MatType.CV_8UC3, Scalar.White);
Cv2.ImWrite("check.png", mat);
Console.WriteLine($"OpenCV バージョン: {Cv2.GetVersionString()}");
Console.WriteLine("check.png を出力しました。正常動作確認完了。");

実行すると以下のように表示され、カレントディレクトリに check.png が生成されます。

OpenCV バージョン: 4.x.x
check.png を出力しました。正常動作確認完了。

ここまで通れば環境構築は完了です。VideoCapture の使い方【OpenCV/C#（OpenCvSharp）】〜カメラ映像を取り込む〜 や Cv2.BitwiseAnd の使い方【OpenCV/C#（OpenCvSharp）】〜ビット演算とマスク処理〜 といった実装記事に進めます。

---

つまずきポイント

⚠️ OpenCvSharp4.runtime.win の存在を知らない

Python の OpenCV（opencv-python）は1パッケージで完結しますが、OpenCvSharp は ラッパー + ネイティブランタイム の2パッケージ構成です。ドキュメントや検索結果で OpenCvSharp4 しか紹介されていないケースがあり、ランタイムを入れ忘れるのがこのエラーの最大の原因です。

⚠️ Linux/Mac では別のランタイムパッケージが必要

OpenCvSharp4.runtime.win は Windows 専用です。Linux では OpenCvSharp4.runtime.ubuntu.xx-x64、macOS では OpenCvSharp4.runtime.osx（またはコミュニティパッケージ）が必要になります。クロスプラットフォームで動かす場合は実行OS に合ったランタイムを追加してください。

⚠️ TypeInitializationException に隠れて見落とす

例外メッセージが TypeInitializationException から始まる場合、根本原因は InnerException に DllNotFoundException として埋まっています。Visual Studio のデバッグウィンドウや exception.InnerException?.Message を確認し、OpenCvSharpExtern というキーワードを見つけたらこの記事の手順を試してください。

---

再発防止

• csproj テンプレートに最初から2パッケージを記載しておく
• CI/CD パイプラインで dotnet restore と dotnet publish を実行し、成果物に OpenCvSharpExtern.dll が含まれるかをファイル存在チェックするステップを追加する
• <PlatformTarget>x64</PlatformTarget> を csproj に明示し、ビルドの曖昧さを排除する

---

まとめ

チェック項目	対処
OpenCvSharp4.runtime.win が未インストール	NuGet で追加する
出力ディレクトリに OpenCvSharpExtern.dll がない	キャッシュクリア後に再ビルド
プラットフォームターゲットの不一致	csproj で x64 を明示
Linux/Mac で runtime.win を使っている	OS に合ったランタイムに変更

DllNotFoundException: OpenCvSharpExtern は C# での OpenCV 導入時の最頻出エラーですが、原因はほぼ「ランタイムパッケージの不足」に集約されます。上記の手順で解決しない場合は、InnerException の内容も合わせて確認してみてください。