vcpkg で OpenCV を導入する完全ガイド【C++/Windows・Linux対応】

「OpenCV を C++ で使いたいが、ビルドは手間がかかる」——vcpkg はその問題をコマンド数行で解決するパッケージマネージャーです。この記事を読み終えると、vcpkg で OpenCV をインストールし、Visual Studio または CMake プロジェクトですぐに #include <opencv2/opencv.hpp> できる状態になります。

前提環境
手順
動作確認
つまずきポイント
まとめ

前提環境

項目	内容
OS	Windows 10/11 または Ubuntu（現行 LTS）
コンパイラ	MSVC（Visual Studio 2022）または GCC/Clang
CMake	3.21 以上
vcpkg	最新安定版（公式リポジトリの HEAD）
OpenCV	4.x（vcpkg が管理するバージョン）

vcpkg は Windows・Linux・macOS に対応していますが、本記事では Windows（MSVC）と Ubuntu（GCC） の手順を中心に説明します。

手順

1. vcpkg 本体を取得する

公式リポジトリをクローンします。インストール先は任意ですが、パスにスペースが含まれない場所を推奨します。

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg

Windows の場合：

.\bootstrap-vcpkg.bat

Linux / macOS の場合：

./bootstrap-vcpkg.sh

ブートストラップが完了すると、vcpkg 実行ファイルが生成されます。

2. OpenCV をインストールする

基本インストール（静的ライブラリ）

.\vcpkg install opencv4:x64-windows

Linux の場合は x64-windows の代わりに x64-linux を指定します。

./vcpkg install opencv4:x64-linux

contrib モジュールを含める場合

SIFT・ORB 拡張など contrib が必要な場合は opencv4[contrib] を指定します。

.\vcpkg install "opencv4[contrib]:x64-windows"

インストール中は依存ライブラリ（zlib・libjpeg・libpng など）も自動で解決されます。ネットワーク環境と PC スペックによりますが、初回は 10〜20 分程度かかります。

インストールが完了したら、一覧で確認します。

.\vcpkg list

opencv4:x64-windows が表示されれば成功です。

3. Visual Studio との統合（Windows のみ）

以下のコマンドを一度実行するだけで、Visual Studio の全プロジェクトに vcpkg のライブラリが自動で認識されるようになります。

.\vcpkg integrate install

実行後に表示されるメッセージを確認してください。

Applied user-wide integration for this vcpkg root.

これ以降、Visual Studio でプロジェクトを作成した際に、インクルードパスとリンクパスが自動設定されます。プロジェクトのプロパティ を手動で変更する必要はありません。

4. CMake プロジェクトとの統合

CMake を使う場合は、CMAKE_TOOLCHAIN_FILE に vcpkg のツールチェーンファイルを渡します。

cmake コマンドで指定する場合：

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build

CMakePresets.json を使う場合（推奨）： プロジェクトルートに CMakePresets.json を置き、toolchainFile を記述しておくと毎回の指定が不要になります。

CMakeLists.txt 側は通常の find_package で問題ありません。

find_package(OpenCV REQUIRED)
target_link_libraries(your_target PRIVATE ${OpenCV_LIBS})

5. 環境変数 PATH の確認（Windows）

vcpkg integrate install を実行済みであれば通常は不要ですが、DLL が見つからないエラーが出る場合は、以下のディレクトリを PATH に追加します。

<vcpkg_root>\installed\x64-windows\bin

動作確認

インストール後、以下の完全プログラムでビルドと実行を確認してください。画像の読み込み・グレースケール変換・保存を行う最小構成です。

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

int main()
{
    // 動作確認用: 100x100 の単色カラー画像を生成して保存する
    cv::Mat src(100, 100, CV_8UC3, cv::Scalar(100, 149, 237));

    // グレースケールに変換
    cv::Mat gray;
    cv::cvtColor(src, gray, cv::COLOR_BGR2GRAY);

    // ファイルに書き出す
    bool ok = cv::imwrite("output_gray.png", gray);
    if (!ok) {
        std::cerr << "[ERROR] imwrite failed." << std::endl;
        return 1;
    }

    // 書き出したファイルを読み直して検証
    cv::Mat loaded = cv::imread("output_gray.png", cv::IMREAD_GRAYSCALE);
    if (loaded.empty()) {
        std::cerr << "[ERROR] imread failed." << std::endl;
        return 1;
    }

    std::cout << "size  : " << loaded.cols << " x " << loaded.rows << std::endl;
    std::cout << "type  : " << loaded.type() << " (CV_8UC1 = " << CV_8UC1 << ")" << std::endl;
    std::cout << "動作確認 OK" << std::endl;

    return 0;
}

実行結果（標準出力）：

size  : 100 x 100
type  : 0 (CV_8UC1 = 0)
動作確認 OK

カレントディレクトリに output_gray.png が生成されていれば、OpenCV のリンクと実行が正常に機能しています。

cv::Mat の型や変換についての詳細は Mat::convertTo の使い方【OpenCV/C++】〜型変換とスケーリング〜を参照してください。

つまずきポイント

⚠️ トリプレット（x64-windows / x86-windows）の取り違え

Visual Studio プロジェクトのプラットフォームが x64 なのに x86-windows でインストールすると、リンクエラー（LNK2019: 外部シンボルの未解決）が発生します。インストール時のトリプレットとプロジェクトのターゲットアーキテクチャを必ず一致させてください。

確認方法：