OpenCV + opencv_contrib を macOS でビルドする完全ガイド【C++/CMake】

macOS で OpenCV + opencv_contrib をソースビルドする
1. 先に結論: Homebrew の OpenCV は contrib を含んでいます
前提環境
手順
動作確認
つまずきポイント
まとめ

macOS で OpenCV + opencv_contrib をソースビルドする

この記事では、macOS 上で OpenCV 本体と opencv_contrib（追加モジュール群）を CMake でソースビルドし、C++ から使える状態にするまでの手順を説明します。手順はすべて、Apple Silicon の Mac で実際に最後までビルドして確認したものです。

先に結論: Homebrew の OpenCV は contrib を含んでいます

「contrib が要るからソースビルドしなければならない」と書かれた記事をよく見かけますが、これは現在では正しくありません。手元の macOS（Apple Silicon）で brew install opencv@4（4.14.0）を入れ、cv::getBuildInformation() を実際に出力して確認しました。

Extra modules:
    Location (extra):    .../opencv_contrib/modules
Non-free algorithms:     YES

contrib モジュールは含まれており、nonfree も有効です。実際に cv::xfeatures2d::SURF::create() が例外なく生成できることも確認しました。つまり contrib を使いたいだけなら brew install opencv@4 で足ります。

それでもソースビルドが必要になるのは、次のいずれかに当てはまる場合です。

ソースビルドが要る理由	具体例
バージョンを固定したい	Homebrew の `opencv` は追従が早く、2026年9月時点で `brew install opencv` は OpenCV 5.0.0 が入ります（後述）。「4.10 系でなければ困る」という固定はソースビルドでしか実現できません
ビルドオプションを制御したい	不要モジュールを外してサイズを削る、静的リンクにする、デバッグシンボル付きでビルドする
配布物に組み込みたい	自社製品に同梱する場合、開発機の Homebrew に依存した構成にはできません

逆に言えば、この3つに当てはまらないなら Homebrew で十分です。

⚠️ そしてバージョンを固定する場合は覚悟が要ります。古い OpenCV を今の Homebrew 環境でビルドすると、新しくなった周辺ツールとの非互換で何か所も止まります。本記事の手順は、実際に踏んだ4か所の回避策を組み込んだものです（詳細はつまずきポイントで）。

前提環境

項目	内容
Mac	Apple M2（8 コア・メモリ 16GB）
Xcode Command Line Tools	インストール済み
CMake	4.4.3（Homebrew）
OpenCV / opencv_contrib	4.10.0（当社 SDK の採用版を例にしています）
インストール先	`$HOME/opencv-4.10`（Homebrew と分ける）

手順

1. Xcode Command Line Tools のインストール

xcode-select --install

すでに導入済みの場合はスキップできます。

2. Homebrew で CMake と pkg-config を入れる

brew install cmake pkg-config

JPEG / PNG / TIFF / WebP などの画像ライブラリは、追加で入れる必要はありません。macOS では BUILD_JPEG / BUILD_PNG / BUILD_TIFF などの既定値が ON で、OpenCV に同梱されたものを最初からビルドする設定になっているためです。Homebrew で jpeg-turbo や libpng を入れていても、この設定のままでは使われません。

3. ソースコードの取得

mkdir ~/opencv_build && cd ~/opencv_build

git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git

cd opencv         && git checkout 4.10.0 && cd ..
cd opencv_contrib && git checkout 4.10.0 && cd ..

⚠️ opencv 本体と opencv_contrib のタグは 必ず一致させてください。CMake の構成段階にはバージョンの食い違いを検出する仕組みが無く、食い違っていても構成は通ってしまいます。問題が表に出るのはビルドの途中で、contrib 側が本体に無い API を呼ぶ形のコンパイルエラーなどとして現れます。

4. CMake 構成

mkdir build && cd build

export CMAKE_POLICY_VERSION_MINIMUM=3.5

cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$HOME/opencv-4.10 \
  -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules \
  -DOPENCV_GENERATE_PKGCONFIG=ON \
  -DOPENCV_ENABLE_NONFREE=ON \
  -DBUILD_JAVA=OFF \
  -DBUILD_opencv_python3=OFF \
  -DBUILD_opencv_python2=OFF \
  -DBUILD_TESTS=OFF \
  -DBUILD_PERF_TESTS=OFF \
  -DBUILD_EXAMPLES=OFF \
  -DWITH_FFMPEG=OFF \
  -DWITH_VTK=OFF \
  ../opencv

主要オプション

オプション	意味
`OPENCV_EXTRA_MODULES_PATH`	contrib モジュールのパス
`OPENCV_GENERATE_PKGCONFIG=ON`	`opencv4.pc` を生成する。OpenCV 4 系は既定で OFF なので、`pkg-config` を使うなら必須
`OPENCV_ENABLE_NONFREE=ON`	SURF など特許関連アルゴリズムを有効化（SIFT は 4.4 以降この指定なしで使える）
`CMAKE_INSTALL_PREFIX`	インストール先。Homebrew のプレフィックスと分ける（`sudo` も不要になる）
`export CMAKE_POLICY_VERSION_MINIMUM=3.5`	CMake 4 系で OpenCV 4.11 以前をビルドするための回避策（後述）
`BUILD_JAVA=OFF` / `WITH_FFMPEG=OFF` / `WITH_VTK=OFF`	今の Homebrew 環境でビルドが止まる箇所の回避策（後述）

WITH_FFMPEG=OFF にしても、macOS では動画の読み書きに AVFoundation が使われます。MPEG-4 と H.264 の mp4 を cv::VideoCapture で読めることを確認しています（同じ検証で、ffmpeg で作った HEVC / VP9 / AV1 の mp4 は開けませんでした。HEVC はファイルのタグ付けの影響もありうるため、ここでは「MPEG-4 / H.264 は読める」までを確認した範囲とします）。

5. ビルドとインストール

make -j$(sysctl -n hw.logicalcpu)
make install

hw.logicalcpu は論理コア数を返します（macOS に nproc はありません）。今回の構成で、Apple M2 で CMake 構成 34 秒・ビルド 3分58秒（56 モジュール）でした。なお検証機には brew install opencv@4 の依存として HDF5・glog / gflags・FreeType などが入っていたため、それらを使う hdf / sfm / freetype モジュールも有効になっています。cmake と pkg-config だけの Mac では、これらは自動で外れてモジュール数が減ります。インストール先は $HOME の下なので sudo は要りません。

6. pkg-config の確認

export PKG_CONFIG_PATH=$HOME/opencv-4.10/lib/pkgconfig:$PKG_CONFIG_PATH
pkg-config --modversion opencv4

4.10.0 と表示されれば成功です。export の行は ~/.zshrc に追記しておきます。

動作確認

ビルド情報を出力し、contrib が nonfree 込みで動くかを確かめる最小プログラムです。

#include <iostream>
#include <opencv2/core.hpp>
#include <opencv2/imgcodecs.hpp>
#include <opencv2/highgui.hpp>
#include <opencv2/features2d.hpp>   // 本体: SIFT（4.4 以降こちら）
#include <opencv2/xfeatures2d.hpp>  // contrib: SURF など

int main()
{
    // ビルド情報を出力して contrib モジュールの有効状態を確認
    std::cout << cv::getBuildInformation() << std::endl;

    // テスト画像の読み込み（カレントディレクトリに test.png を用意する）
    cv::Mat img = cv::imread("test.png");
    if (img.empty()) {
        std::cerr << "画像の読み込みに失敗しました。パスを確認してください。" << std::endl;
        return 1;
    }

    // SIFT は OpenCV 4.4 以降、contrib ではなく本体（features2d）にある
    auto sift = cv::SIFT::create();
    std::vector<cv::KeyPoint> keypoints;
    sift->detect(img, keypoints);
    std::cout << "SIFT 検出キーポイント数: " << keypoints.size() << std::endl;

    // contrib + NONFREE が効いているかは SURF で確認する
    auto surf = cv::xfeatures2d::SURF::create();
    std::vector<cv::KeyPoint> surf_kp;
    surf->detect(img, surf_kp);
    std::cout << "SURF 検出キーポイント数: " << surf_kp.size() << std::endl;

    cv::imshow("test", img);
    cv::waitKey(0);
    return 0;
}

コンパイルと実行

g++ -std=c++17 main.cpp $(pkg-config --cflags --libs opencv4) \
  -Wl,-rpath,$HOME/opencv-4.10/lib -o main
./main

⚠️ -Wl,-rpath,... を忘れると起動しません。 OpenCV の dylib は @rpath 付きの名前で作られるため、Homebrew と分けた場所にインストールすると、実行時に次のエラーになります。

dyld[37214]: Library not loaded: @rpath/libopencv_gapi.410.dylib

実行すると、cv::getBuildInformation() の出力に次の行が含まれます。

    Location (extra):            /Users/<ユーザー名>/opencv_build/opencv_contrib/modules
    Non-free algorithms:         YES

続けて「SURF 検出キーポイント数: （整数）」が出力されれば、contrib が nonfree 込みで動いています。SIFT のほうは本体のモジュールなので、contrib の確認材料にはなりません。

Ubuntu での手順は OpenCV + opencv_contrib を Ubuntu でビルドする完全ガイド【C++】を参照してください。

つまずきポイント

⚠️ 今の Homebrew で OpenCV 4.10.0 をビルドすると止まる4か所

手順4のオプションは、次の4か所で実際にビルドが止まったための回避策です。どれも「OpenCV が古く、周辺ツールが新しい」ことが原因なので、バージョンを固定してソースビルドする人ほど踏みます。

止まる箇所	実際のエラー	原因	回避策
pkg-config の生成	`Compatibility with CMake < 3.5 has been removed from CMake.`	CMake 4 系が古い互換指定を廃止。OpenCV 4.11.0 までの `cmake/OpenCVGenPkgconfig.cmake` が該当（4.12.0 で修正）	`export CMAKE_POLICY_VERSION_MINIMUM=3.5`
Java ラッパー	`modules/java/jar/...` の Java コンパイルエラー	JDK が入っている Mac では Java ラッパーのビルドが自動で有効になる	`-DBUILD_JAVA=OFF`
contrib の `viz`	`no member named 'cout' in namespace 'std'`	Homebrew の VTK（9.6 以降）が `<iostream>` を読み込まなくなった	`-DWITH_VTK=OFF`
`videoio`	`use of undeclared identifier 'avcodec_close'` ほか	FFmpeg 8.0（`avcodec_close` など）と 9.0（`AVCodec.pix_fmts` など）で削除された API を OpenCV 4.10.0 が使っている。Homebrew の現行は 9.0.1	`-DWITH_FFMPEG=OFF`（macOS は AVFoundation で動画を扱える）

特に1つ目は注意が必要です。この回避策は -DCMAKE_POLICY_VERSION_MINIMUM=3.5 と cmake の引数で渡しても効きません。pkg-config の生成は別プロセスの CMake で動くため、引数が伝わらないからです（実際に試して、同じエラーで止まりました）。環境変数として export する必要があります。

参考までに、Homebrew 自身も opencv@4 のビルドで Java を OFF にし、FFmpeg 9 と VTK 向けのパッチを当てています。

⚠️ SIFT は contrib ではなく本体にある（OpenCV 4.4 以降）

古い記事の多くが cv::xfeatures2d::SIFT::create() と書いていますが、SIFT は OpenCV 4.4.0 で本体（features2d）へ移動済みです。特許が 2020年3月に失効したためで、現在この書き方はコンパイルエラーになります。

error: no member named 'SIFT' in namespace 'cv::xfeatures2d'; did you mean 'cv::SIFT'?

一方 SURF は現在も nonfree のままです。OPENCV_ENABLE_NONFREE=ON を付けずにビルドすると、コンパイルとリンクは通りますが、cv::xfeatures2d::SURF::create() が実行時に次のメッセージの例外を投げます。

This algorithm is patented and is excluded in this configuration; Set OPENCV_ENABLE_NONFREE CMake option and rebuild the library

⚠️ brew install opencv を実行したら、既存のビルドが一斉に壊れた

2026年9月時点で、Homebrew の opencv は 5.0.0 です。5.x が提供する pkg-config ファイルは opencv5.pc に変わるため、opencv4.pc が見つからなくなり、pkg-config --cflags --libs opencv4 に依存したビルドがまとめて失敗します。

Package opencv4 was not found in the pkg-config search path.
Perhaps you should add the directory containing `opencv4.pc'
to the PKG_CONFIG_PATH environment variable

当社でも実際にこれを踏み、それまで通っていたビルドがある日まとめて落ちました。4 系を使い続けるなら opencv@4 を入れます。

brew install opencv@4

opencv@4 は keg-only（/opt/homebrew 直下にリンクされない）なので、入れただけでは pkg-config から見えません。PKG_CONFIG_PATH を通します。

export PKG_CONFIG_PATH="$(brew --prefix opencv@4)/lib/pkgconfig:$PKG_CONFIG_PATH"
pkg-config --modversion opencv4

4.14.0 のように 4 系のバージョンが返れば復旧しています。

brew link --overwrite opencv@4 で直接リンクする方法もありますが、5 系（opencv）のリンクが外れます。以後は brew upgrade のたびにリンクの取り合いになるので、5 系を使わないと決めている場合以外は PKG_CONFIG_PATH を勧めます。

まとめ

contrib を使いたいだけなら brew install opencv@4 で足りる。ソースビルドはバージョン固定・オプション制御・配布物への同梱のため
本体と contrib は 同じタグ で clone する
CMake には OPENCV_EXTRA_MODULES_PATH・OPENCV_GENERATE_PKGCONFIG=ON・OPENCV_ENABLE_NONFREE=ON を指定し、インストール先は $HOME/opencv-4.10 のように Homebrew と分ける
古い OpenCV を今の Homebrew でビルドするなら、CMAKE_POLICY_VERSION_MINIMUM（環境変数）/ BUILD_JAVA=OFF / WITH_VTK=OFF / WITH_FFMPEG=OFF の4つの回避策を入れる
自分のプログラムは -Wl,-rpath,$HOME/opencv-4.10/lib を付けてリンクし、SURF の検出で contrib + nonfree の動作を確認する