Ubuntu に OpenCV をインストールする完全ガイド【C++/apt・ソースビルド】

Ubuntu で C++ の OpenCV 開発環境を構築する手順を、apt による簡易インストールとソースからのビルドの2通りで解説します。

apt 版は手軽に始められますが、バージョンが古い・contrib モジュールが含まれない・ビルドオプションが固定されているという制約があります。本番プロジェクトや特定バージョンが必要な場合はソースビルドを選んでください。この記事を読み終えると、どちらの方法でも pkg-config を通じて C++ プログラムをコンパイルできる状態になります。

---

前提環境

項目	バージョン
OS	Ubuntu 24.04 LTS（22.04 LTS でも手順は同様）
コンパイラ	GCC 13 系（g++ コマンド）
CMake	3.20 以上（ソースビルド時）
OpenCV	4.x 系（apt 版はディストリ依存）

---

方法 1: apt でインストール（手軽・推奨スタート）

手順

ステップ 1 — パッケージリストを更新する

sudo apt update

ステップ 2 — OpenCV 開発パッケージをインストールする

sudo apt install -y libopencv-dev

libopencv-dev には C++ ヘッダー・ライブラリ・pkg-config ファイルがすべて含まれます。

ステップ 3 — インストールされたバージョンを確認する

pkg-config --modversion opencv4

バージョン番号（例: 4.6.0）が表示されれば成功です。

ステップ 4 — コンパイルが通るか確認する

g++ -std=c++17 main.cpp $(pkg-config --cflags --libs opencv4) -o main

---

方法 2: ソースからビルド（バージョン指定・カスタマイズ向け）

apt 版では満たせない要件（特定バージョン固定・opencv_contrib の組み込み・TBB/CUDA 有効化など）がある場合はこちらを使います。

手順

ステップ 1 — 依存パッケージをインストールする

sudo apt update
sudo apt install -y \
  build-essential cmake git pkg-config \
  libgtk-3-dev \
  libavcodec-dev libavformat-dev libswscale-dev \
  libtbb-dev \
  libjpeg-dev libpng-dev libtiff-dev \
  libwebp-dev libopenexr-dev

GUI（imshow）を使わないヘッドレス環境では libgtk-3-dev は省略できます。

ステップ 2 — ソースを取得する

git clone https://github.com/opencv/opencv.git
cd opencv
git checkout 4.x          # 最新の 4.x ブランチを使う場合
cd ..

opencv_contrib（SIFT・ArUco などの追加モジュール）も使う場合は次も実行します。

git clone https://github.com/opencv/opencv_contrib.git
cd opencv_contrib
git checkout 4.x
cd ..

ステップ 3 — CMake でビルドを構成する

mkdir opencv/build && cd opencv/build

cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local \
  -DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
  -DBUILD_EXAMPLES=OFF \
  -DBUILD_TESTS=OFF \
  -DBUILD_PERF_TESTS=OFF \
  ..

opencv_contrib を使わない場合は -DOPENCV_EXTRA_MODULES_PATH 行を削除してください。

ステップ 4 — ビルドしてインストールする

make -j$(nproc)
sudo make install
sudo ldconfig

-j$(nproc) は論理コア数を自動で使うオプションです。8 コアマシンなら -j8 相当になります。

ステップ 5 — pkg-config が通るか確認する

pkg-config --modversion opencv4

/usr/local/lib/pkgconfig/ に .pc ファイルが置かれていれば即座に認識されます。表示されない場合は以下を実行してください。

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH

恒久的に設定する場合は ~/.bashrc に追記します。

---

動作確認

インストール後、次のプログラムでビルドと OpenCV の初期化を確認します。

#include <iostream>
#include <opencv2/opencv.hpp>

int main()
{
    // ビルド情報を出力して環境が正しいことを確認する
    std::cout << cv::getBuildInformation() << std::endl;

    // 単色の小さな画像を生成してファイルに書き出す
    cv::Mat img(100, 200, CV_8UC3, cv::Scalar(64, 128, 200));

    // BGR → グレースケール変換
    cv::Mat gray;
    cv::cvtColor(img, gray, cv::COLOR_BGR2GRAY);

    // ファイル書き出し
    if (!cv::imwrite("output.png", gray))
    {
        std::cerr << "imwrite に失敗しました" << std::endl;
        return 1;
    }

    std::cout << "output.png を書き出しました" << std::endl;
    return 0;
}

コンパイルと実行

g++ -std=c++17 main.cpp $(pkg-config --cflags --libs opencv4) -o main
./main

実行すると、ターミナルに getBuildInformation() の結果（OpenCV バージョン・有効モジュール・コンパイラ情報など）が出力され、その後 output.png を書き出しました と表示されます。カレントディレクトリに output.png（200×100 のグレースケール画像）が生成されていれば成功です。

getBuildInformation() の出力で opencv_contrib モジュールや TBB 等のオプションが有効になっているかも確認できます。

---

つまずきポイント

⚠️ pkg-config --modversion opencv4 が失敗する

apt 版は正しく .pc ファイルが置かれますが、ソースビルド後に /usr/local/lib/pkgconfig が PKG_CONFIG_PATH に含まれていないと見つからない場合があります。

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
pkg-config --modversion opencv4

それでも失敗する場合は .pc ファイルの存在を確認します。

find /usr/local -name "opencv4.pc"

⚠️ undefined reference to cv::... のリンクエラー

コンパイルコマンドに $(pkg-config --cflags --libs opencv4) が抜けていることが原因です。--libs を省略するとヘッダーは見つかってもリンクに失敗します。また、pkg-config の展開結果は コンパイル対象のソースファイルより後ろ に書く必要があります。

# NG: ソースより前にオプションを書くとリンクが通らないケースがある
g++ $(pkg-config --cflags --libs opencv4) main.cpp -o main

# OK
g++ -std=c++17 main.cpp $(pkg-config --cflags --libs opencv4) -o main

⚠️ imwrite が失敗する（空の Mat や書き込み権限）

imwrite は書き込み先ディレクトリの権限がない場合や、拡張子が対応フォーマット（.png .jpg .tiff など）以外の場合に false を返して失敗します。imread で読み込んだ画像が空 Mat になっているケースも多く、imread 直後に empty() チェックを入れる習慣をつけてください。

if (img.empty()) {
    std::cerr << "画像の読み込みに失敗しました（パスを確認）" << std::endl;
    return 1;
}

日本語を含むパスは Linux でも文字コード次第で問題が起きることがあります。ASCII パスで試してから絞り込むと効率的です。

---

まとめ

	apt	ソースビルド
手軽さ	✅ コマンド1本	❌ 手順が多い
バージョン	ディストリ依存（古い場合あり）	任意
contrib モジュール	❌ 含まれない	✅ 組み込み可
ビルドオプション	固定	✅ 自由

プロトタイプや学習用途なら apt、製品開発やバージョン固定・contrib が必要なら ソースビルドを選んでください。

パッケージマネージャーで複数プロジェクトのバージョンを管理したい場合は、vcpkg で OpenCV を導入する完全ガイド【C++/Windows・Linux対応】 も参照してください。vcpkg はライブラリごとにバージョンを分離して管理できるため、複数プロジェクトを並行開発する環境に向いています。

環境構築後の実装例として、cv::VideoCapture の使い方【OpenCV/C++】〜カメラ映像を取り込む〜 や cv::QRCodeDetector の使い方【OpenCV/C++】〜QRコードを読み取る〜 も合わせてご覧ください。