---
title: "OpenCVとは？Pythonでの使い方入門｜pip installから画像処理・顔検出まで【5.0対応】"
url: "https://www.issoh.co.jp/tech/details/1344/"
published: 2023-09-13
updated: 2026-10-11
categories: ["Python"]
publisher: "株式会社一創"
---

# OpenCVとは？Pythonでの使い方入門｜pip installから画像処理・顔検出まで【5.0対応】

OpenCV（オープンシーブイ）は、画像や動画の処理・解析を行うオープンソースのライブラリです。Pythonでは`pip install opencv-python`で入れ、`import cv2`で呼び出します。2026年6月に出たOpenCV 5.0では、昔の入門記事で定番だったHaar Cascadeの顔検出（`cv2.CascadeClassifier`）が標準パッケージから外れ、古いコードをそのまま貼ると`AttributeError`で止まります。この記事では、パッケージと版の選び方から、画像の読み込み・グレースケール・リサイズ・エッジ検出・輪郭抽出・動画の背景差分・顔検出までを、5.0.0と4.14.0の両方で実行して確認したコードで説明します。

## まとめ：OpenCVをPythonで使う要点

- OpenCVは1999年にIntelで始まった画像処理ライブラリで、4.5.0からApache 2.0ライセンス。商用でも無料で使えます。
- インストールは`pip install opencv-python`。`pip install cv2`というパッケージは存在しません。4種類あるパッケージ（標準・contrib・headless 2種）は**1つだけ**入れます。
- 2026年10月時点のPyPI最新は5.0.0.93（2026-07-02）。4系も4.14.0.94（日本時間2026-07-29公開）が出ており保守が続いています。
- 5.0ではHaar Cascade・HOG・`readNetFromCaffe`が標準版から消えました。新しく書くなら顔検出はYuNet（`cv2.FaceDetectorYN`）、既存コードを動かすだけなら`pip install "opencv-python<5"`で4系に留めます（現時点では4.14.0.94が入ります）。
- 読み込んだ画像はNumPy配列で、色の並びは**BGR**。matplotlibやPillowに渡す前に`cv2.COLOR_BGR2RGB`で並べ替えます。

## OpenCVとは：Pythonでは「cv2」として使う画像処理ライブラリ

OpenCVはOpen Source Computer Vision Libraryの略です。本体はC++で書かれており、PythonからはC++の関数をラップした`cv2`モジュールとして使います。画像はNumPyの配列（`numpy.ndarray`）として受け渡すため、ピクセル単位の計算や切り抜きはNumPyの書き方がそのまま使えます。配列の基本は[NumPyとは？読み方・インストール・基本的な使い方をPythonで解説](/tech/details/3124/)で確認できます。

### OpenCVの読み方・開発経緯・ライセンス

読み方は「オープンシーブイ」です。プロジェクトは1999年にIntel Researchの取り組みとして始まり、その後Willow Garage、Itseez（2016年にIntelが買収）へと開発の中心が移りました。現在はOpenCV.orgとコミュニティが開発しています。

ライセンスは版で変わっています。[4.4.0のLICENSE](https://github.com/opencv/opencv/blob/4.4.0/LICENSE)は3条項BSDライセンスでしたが、[4.5.0からApache License 2.0](https://github.com/opencv/opencv/blob/4.5.0/LICENSE)になりました。どちらも商用利用・改変・再配布ができますが、Apache 2.0は特許の許諾条項を持ちます。社内の利用審査では「BSD」と書かれた古い資料のままにせず、使う版のLICENSEファイルで確かめてください。

### OpenCVでできること：処理と代表関数

OpenCVは画像1枚の加工にとどまらず、動画・カメラ入力・特徴点・学習済みモデルの推論までを1つのライブラリで扱えます。「何ができるか」を、Pythonで呼ぶ関数名と合わせて整理します。

| 分野       | 代表的な関数・クラス                           | 本記事の章   |
| -------- | ------------------------------------ | ------- |
| 入出力      | imread / imwrite / imshow            | 画像の読み込み |
| 色変換・幾何変換 | cvtColor / resize / warpAffine       | 基本の画像処理 |
| フィルタ・二値化 | GaussianBlur / threshold             | 基本の画像処理 |
| 特徴抽出     | Canny / findContours / ORB\_create   | 基本の画像処理 |
| 動画・カメラ   | VideoCapture / VideoWriter           | 動画・カメラ  |
| 動体検知     | createBackgroundSubtractorMOG2       | 動画・カメラ  |
| 顔・物体検出   | FaceDetectorYN / dnn.readNetFromONNX | 顔検出     |

一方で、深層学習モデルを一から学習させる用途はOpenCVの守備範囲外です。学習はPyTorchなどで行い、OpenCVは前処理と推論に使う分担が一般的です。ライブラリの組み合わせ方は[画像認識のPythonライブラリ比較｜PyTorch・OpenCV・YOLOの選び方とライセンス](/column/details/7417/)で比べています。

### PillowとOpenCVの使い分け

リサイズ・形式変換・文字入れだけならPillowで足ります。エッジ検出・輪郭・動画・顔検出が入るならOpenCVを選びます。

| 観点       | Pillow      | OpenCV（cv2）             |
| -------- | ----------- | ----------------------- |
| 主な用途     | 加工・形式変換     | 画像解析・検出・動画              |
| 色の並び     | RGB         | BGR                     |
| データ形式    | Imageオブジェクト | NumPy配列                 |
| 動画・カメラ   | 扱わない        | VideoCaptureで扱う         |
| 日本語の文字描画 | フォント指定で可    | 標準putText：5.0は可・4.14は不可 |

文字入れは版で事情が変わりました。4.14の`cv2.putText`は日本語を「?」に置き換えて描きますが、5.0は文字描画がTrueTypeエンジンに替わり、`cv2.FONT_HERSHEY_SIMPLEX`を指定したままでも「日本語」と描けます（5.0.0.93と4.14.0.94で確認）。4系を使う間は、日本語の文字入れだけPillowに任せる併用が定番です。Pillow側の書き方は[Pillowとは？Pythonの画像処理ライブラリの使い方をコード付きで解説](/tech/details/1343/)にまとめています。

## OpenCVをインストールする：pip install opencv-python

Pythonでは公式のビルド済みパッケージをpipで入れます。使用環境に対応するwheelがあれば、ソースからのビルドは不要です。PyPIの[opencv-python](https://pypi.org/project/opencv-python/)は`cp37-abi3`のwheelで配布されており、Python 3.7以降ならWindows・macOS・Linuxに同じ手順で入ります。macOS向けwheelはApple Silicon版がmacOS 13以降、Intel版がmacOS 14以降です。

```
python -m venv .venv
source .venv/bin/activate      # Windowsは .venv\Scripts\activate
pip install --upgrade pip
pip install opencv-python
python -c "import cv2; print(cv2.__version__)"
```

Python 3.9以降では依存として`numpy>=2`が入ります（5.0.0.93・4.14.0.94とも同じ）。NumPy 1系に固定している既存環境へ入れると、他のパッケージとの依存がぶつかることがあるので、仮想環境を分けておくのが安全です。

### OpenCVの4種類のパッケージと選定基準

OpenCVのpipパッケージは4種類あります。opencv-pythonのREADMEは「4つのうち1つだけを選び、同じ環境に複数入れないこと」と明記しています。どれも同じ`cv2`という名前で入るため、2つ入れると後から入れた方が上書きし、関数が見つからない不具合の原因になります。

| パッケージ                          | GUI（imshow） | contrib | 向く環境           |
| ------------------------------ | ----------- | ------- | -------------- |
| opencv-python                  | あり          | なし      | デスクトップ環境       |
| opencv-contrib-python          | あり          | あり      | デスクトップで追加機能も使う |
| opencv-python-headless         | なし          | なし      | サーバー・Docker    |
| opencv-contrib-python-headless | なし          | あり      | サーバーで追加機能も使う   |

contribは追加アルゴリズムを集めたモジュール群で、5.0からはHaar Cascadeもここに移りました。ただし、SURFのように特許が絡むアルゴリズムはcontrib版のpipパッケージにも含まれません（SIFTは特許切れのため4.3.0から入っています）。間違えて複数入れた場合は、すべて`pip uninstall`してから1つだけ入れ直します。

### OpenCV 5.0と4.14の選定基準

何も指定しなければ5.0.0.93が入ります。ただし4系の保守は止まっておらず、5.0.0.93の約4週間後に4.14.0.94がPyPIに公開されています（[OpenCVのリリース一覧](https://github.com/opencv/opencv/releases)でも4.14.0は2026-07-19、5.0.0は2026-06-06）。判断の基準は、動かしたいコードが5.0で消えた機能を使っているかどうかです。

| 状況                   | 入れる版 | コマンド                          |
| -------------------- | ---- | ----------------------------- |
| 新しく書き始める             | 5.0  | pip install opencv-python     |
| Haar・HOGを使う既存コード     | 4系   | pip install “opencv-python<5” |
| Caffe・Darknetのモデルを読む | 4系   | pip install “opencv-python<5” |
| cv2.ml（SVM等）を使う      | 4系   | pip install “opencv-python<5” |

公式の[OpenCV 4から5への移行ガイド](https://github.com/opencv/opencv/wiki/OpenCV-4-to-5-migration)によると、Pythonでは関数の置き場所が変わっても`cv2.関数名`の呼び方は変わりません。`calib3d`の分割や`features2d`の改名も、Pythonのコードは書き換え不要です。主な削除・移動は上の表の3種類で、`CascadeClassifier`と`HOGDescriptor`はcontribへ移動、`readNetFromCaffe`と`readNetFromDarknet`は削除（ONNXへ変換して`readNetFromONNX`で読む）、`cv2.ml`はcontribでビルドしないと使えません。呼び出し名が同じでも結果が変わる変更もあります。NumPyの1次元配列は列ベクトルでなく1次元の`Mat`として渡るようになり、`VideoCapture.get()`は未対応のプロパティに4系の`0`ではなく`-1`を返します。`putText`の文字の見た目も変わります。

「4系の最新」ではなく特定の版に固定したいときは、`==`で完全に指定します。

```
pip install opencv-python==5.0.0.93
# 4系に固定する場合
pip install opencv-python==4.14.0.94
```

### import cv2 で ModuleNotFoundError になるとき

`import cv2`で`ModuleNotFoundError: No module named 'cv2'`が出たら、OpenCVを入れた環境と実行しているPythonが一致しているかをまず疑います。モジュール名に合わせて`pip install cv2`と打っても、PyPIに`cv2`というパッケージは無いため、次のエラーで終わります。

```
ERROR: Could not find a version that satisfies the requirement cv2 (from versions: none)
ERROR: No matching distribution found for cv2
```

正しくは`opencv-python`（または上の表のどれか1つ）を、実行に使うPythonで入れます。`python -m pip install opencv-python`のように`python -m pip`で呼ぶと、インストール先と実行環境のずれを避けられます。VS CodeやJupyterでは、選んでいるインタプリタが仮想環境を指しているかも確認してください。

## 画像の読み込み・表示・保存

読み込みは`imread`、表示は`imshow`、保存は`imwrite`です。次の例のようにJPEGを既定の設定で読み込むと、画像は`(高さ, 幅, 3)`の配列で、要素は0〜255の`uint8`です。

```
import cv2

img = cv2.imread("input.jpg")          # BGRの順で読み込む
if img is None:                         # ファイルが無くても例外にならない
    raise FileNotFoundError("input.jpgを読み込めません")

print(img.shape, img.dtype)             # 例: (512, 512, 3) uint8
face = img[100:300, 150:350]            # 切り抜きはNumPyのスライス [y1:y2, x1:x2]

cv2.imshow("preview", img)              # ウィンドウ表示
cv2.waitKey(0)                          # キー入力まで待つ（無いと即閉じる）
cv2.destroyAllWindows()

cv2.imwrite("output.png", img)          # 拡張子で保存形式が決まる
cv2.imwrite("output.jpg", img, [cv2.IMWRITE_JPEG_QUALITY, 90])
```

`imread`はファイルが無い・パスに誤りがあるときも例外を投げず、警告を出して`None`を返します。チェックを省くと、後段の`cvtColor`で原因の分かりにくいエラーになります。

### imshowが使えない環境：サーバー・Docker・Colab

`imshow`はGUIのウィンドウを開くため、画面の無いサーバーやDockerでは使えません。Linux向けのheadless版はQtなどのGUI部品を含まないビルドです（macOS向けのheadless版は`cv2.getBuildInformation()`でGUI: COCOAと出るビルドで、`imshow`は動きました）。こうした環境では`imwrite`でファイルに書き出して確認します。Google Colabでは`from google.colab.patches import cv2_imshow`の`cv2_imshow(img)`を使います。matplotlibで表示する場合は、次の章のBGR→RGB変換を挟みます。

## 基本的な画像処理のPython実装

ここからは、前の章で読み込んだ`img`を入力にします。どの処理もグレースケールへの変換から始まることが多いので、その順で説明します。

### グレースケール変換と色の並び（BGR→RGB）

色空間の変換は`cvtColor`です。グレースケールは`COLOR_BGR2GRAY`を指定します。

```
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)     # shapeは (高さ, 幅) の2次元になる
cv2.imwrite("gray.png", gray)

# 未導入の場合は、先にターミナルで python -m pip install matplotlib を実行
import matplotlib.pyplot as plt
rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)       # matplotlib・PillowはRGB
plt.imshow(rgb)
plt.show()
```

OpenCVは赤い画素を`[0, 0, 255]`（B, G, R）として持ちます。RGB前提のmatplotlibやPillowにそのまま渡すと赤と青が入れ替わります。`imwrite`で保存する分にはBGRのままで正しい色になります。

### リサイズ：サイズ指定は（幅, 高さ）の順

`resize`は絶対サイズでも倍率でも指定できます。縮小は`INTER_AREA`、拡大は`INTER_CUBIC`を選ぶと劣化が目立ちにくくなります。

```
resized = cv2.resize(img, (300, 200))            # 幅300・高さ200
print(resized.shape)                             # (200, 300, 3) ＝ shapeは高さが先

half = cv2.resize(img, None, fx=0.5, fy=0.5, interpolation=cv2.INTER_AREA)
big = cv2.resize(img, None, fx=2.0, fy=2.0, interpolation=cv2.INTER_CUBIC)
```

引数は`(幅, 高さ)`、`shape`は`(高さ, 幅, チャンネル)`と順序が逆です。縦横比を保つなら、`h, w = img.shape[:2]`で元の大きさを取ってから計算します。

### エッジ検出：Canny

エッジ検出は`Canny`が定番です。ぼかしでノイズを落としてから、2つのしきい値を渡します。

```
blurred = cv2.GaussianBlur(gray, (5, 5), 0)     # 先にノイズを減らす
edges = cv2.Canny(blurred, 100, 200)            # 下限100・上限200
cv2.imwrite("edges.png", edges)
```

上限より強い勾配は確実にエッジ、下限未満は捨て、その間は確実なエッジにつながる場合だけ残します。上限を上げると線が減り、下げると細かな模様まで拾います。しきい値の決め方とSobelなど微分フィルタとの使い分けは[エッジ検出とは？Canny法と微分フィルタの使い分けをOpenCVの実装で解説](/tech/details/16854/)で掘り下げています。

### 二値化と輪郭抽出：threshold / findContours

`findContours`は**黒の背景にある白い領域**の輪郭を探します。白い背景の写真をそのまま二値化すると、背景全体が1つの輪郭として返り、対象物を数えられません。白背景なら`THRESH_BINARY_INV`で白黒を反転させます。

```
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)

contours, hierarchy = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
for c in contours:
    if cv2.contourArea(c) < 100:              # 小さなノイズは除外
        continue
    x, y, w, h = cv2.boundingRect(c)
    cv2.rectangle(img, (x, y), (x + w, y + h), (0, 255, 0), 2)
print("輪郭の数:", len(contours))
```

白い背景に赤い四角と青い円を描いた320×240の画像で試すと、`THRESH_BINARY`では輪郭が1つ（画像の外枠）、`THRESH_BINARY_INV`では2つ（面積7,704と10,800）になりました。`THRESH_OTSU`を足すと、しきい値（ここでは0）を無視して大津の方法で自動決定します。照明ムラがある画像の適応的二値化は[二値化とは？しきい値の決め方と大津・適応的の使い分けをOpenCVの実装で解説](/tech/details/16847/)を参照してください。

`RETR_EXTERNAL`は一番外側の輪郭だけを取る指定で、部品を数えるときに使います。穴の内側まで要るなら`RETR_TREE`です。戻り値は4系・5系とも`(contours, hierarchy)`の2つで、3系の3つとは異なります（古いコードの直し方は後の章で扱います）。特定の部品の位置を探したいだけなら、[テンプレートマッチングとは？matchTemplateの仕組みと類似度指標の選び方を解説](/tech/details/16853/)の方法が早い場合もあります。

## 動画・カメラを処理する：VideoCaptureと背景差分

動画は「画像を1枚ずつ取り出して処理する」の繰り返しです。`VideoCapture`にファイル名を渡すと動画ファイル、`0`を渡すとPCの内蔵カメラやUSBカメラが入力になります。

### カメラ映像の動体検知：MOG2による背景差分

背景差分（MOG2）は、動かない背景を学習し、そこから外れた画素を前景として取り出します。監視カメラの動体検知や、固定カメラでの背景除去に使う方法です。

```
import cv2

cap = cv2.VideoCapture(0)                       # 動画ファイルなら "input.mp4"
if not cap.isOpened():
    raise RuntimeError("カメラを開けません")

sub = cv2.createBackgroundSubtractorMOG2(history=500, varThreshold=16, detectShadows=True)

while True:
    ok, frame = cap.read()
    if not ok:                                  # 動画の終端・カメラ切断
        break
    mask = sub.apply(frame)                     # 前景=255、影=127、背景=0
    _, mask = cv2.threshold(mask, 200, 255, cv2.THRESH_BINARY)   # 影を落とす
    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
    for c in contours:
        if cv2.contourArea(c) > 500:
            x, y, w, h = cv2.boundingRect(c)
            cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 0, 255), 2)
    cv2.imshow("motion", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):       # qキーで終了
        break

cap.release()
cv2.destroyAllWindows()
```

`detectShadows=True`では影が127という中間値で出るため、255だけを残すしきい値処理を挟んでいます。前後のフレームの差を自分で取る場合は、`uint8`同士の引き算が桁あふれする点に注意します。10−26はNumPyでは240になりますが、`cv2.absdiff`なら16が返ります。Raspberry Piのカメラで動体を検知して録画するまでの構成は[ラズパイでAI監視カメラを作る方法｜カメラの選び方とAI Camera（IMX500）で人を検知して録画するまで](/tech/details/6731/)で扱っています。

### 処理結果の動画保存：VideoWriterの設定

保存は`VideoWriter`で、コーデック・フレームレート・フレームサイズを指定します。次の例は動画を読み、グレースケールにして別ファイルへ書き出します。元動画の大きさとfpsを取って渡すので、縦横比と再生速度が保たれます。

```
import cv2

cap = cv2.VideoCapture("input.avi")
fps = cap.get(cv2.CAP_PROP_FPS)                  # 取得できないと4.14は0、5.0は-1
if fps <= 0:
    fps = 30.0
w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))

out = cv2.VideoWriter("result.avi", cv2.VideoWriter_fourcc(*"MJPG"), fps, (w, h))
if not out.isOpened():
    raise RuntimeError("VideoWriterを開けません（コーデックと拡張子の組み合わせを確認）")

while True:
    ok, frame = cap.read()
    if not ok:
        break
    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    out.write(cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR))   # 3チャンネルに戻して書く

cap.release()
out.release()
```

書き込むフレームの大きさは、`VideoWriter`に指定した（幅, 高さ）と一致させます。`MJPG`で640×480を指定して320×240のフレームを渡すと、`(-215:Assertion failed) imgWidth == frameWidth`で止まりました。保存形式も環境に左右されます。pipで入るmacOS版はFFmpegを含まないビルド（`cv2.getBuildInformation()`のVideo I/OでFFMPEG: NO）で、`mp4v`＋`.mp4`では`out.isOpened()`が`False`になりファイル自体が作られませんでした。書き出し前に`isOpened()`を確かめ、迷ったら`MJPG`＋`.avi`を使うと5.0・4.14とも読み書きできます。

## 顔検出を実装する：5.0の標準はYuNet

多くの入門記事は`cv2.CascadeClassifier`（Haar Cascade）で顔を検出しています。しかし`pip install opencv-python`で入る5.0.0.93にはこのクラスが無く、次のエラーになります。

```
AttributeError: module 'cv2' has no attribute 'CascadeClassifier'
```

5.0の標準パッケージで顔検出をするなら、深層学習モデルのYuNetを使う`cv2.FaceDetectorYN`に切り替えます。移行ガイドも、新規の開発ではこちらを勧めています。

### YuNet（FaceDetectorYN）による顔検出の実装

モデルは[opencv\_zooのface\_detection\_yunet](https://github.com/opencv/opencv%5Fzoo/tree/main/models/face%5Fdetection%5Fyunet)で配布されています。2026年5月に追加された`face_detection_yunet_2026may.onnx`（約230KB）が既定のモデルで、入力サイズが可変のため5.0のONNX Runtimeエンジンでもそのまま動きます。

```
curl -L -o face_detection_yunet_2026may.onnx \
  https://github.com/opencv/opencv_zoo/raw/main/models/face_detection_yunet/face_detection_yunet_2026may.onnx
```

```
import cv2

img = cv2.imread("photo.jpg")
if img is None:
    raise FileNotFoundError("photo.jpgを読み込めません")
h, w = img.shape[:2]

detector = cv2.FaceDetectorYN.create(
    "face_detection_yunet_2026may.onnx", "", (w, h), score_threshold=0.9)
detector.setInputSize((w, h))                   # 画像ごとに入力サイズを合わせる

_, faces = detector.detect(img)                 # 顔が無いときは None
faces = [] if faces is None else faces

for f in faces:
    x, y, fw, fh = map(int, f[:4])              # 0〜3: 枠、4〜13: 目・鼻・口角、14: スコア
    cv2.rectangle(img, (x, y), (x + fw, y + fh), (0, 255, 0), 2)

print("検出した顔の数:", len(faces))
cv2.imwrite("faces.png", img)
```

OpenCV同梱のサンプル画像`lena.jpg`（512×512）では、5.0.0でも4.14.0でも顔を1つ、スコア0.909で検出しました。`FaceDetectorYN`は4系にもあるため、このコードは両方の版で同じように動きます。YuNetが検出できる顔の大きさはおよそ10×10〜300×300ピクセルです（モデルのREADMEより）。大きく写った顔を取りこぼすときは、画像を縮小してから渡します。

顔以外の物体（人・車・製品の欠陥など）を検出したい場合は、YOLOなどの検出モデルをONNXで書き出し、`cv2.dnn.readNetFromONNX`で読む構成になります。手法の比較は[物体検出とは？仕組み・代表手法の比較から実装判断までエンジニア向けに解説](/tech/details/15323/)にまとめています。検出モデルの学習データ作りから現場の検査工程への組み込みまでを任せたい場合は、[画像認識AIモデル構築の支援](/service/ai/image%5Frecog/)もご相談いただけます。

### Haar Cascadeを使い続ける場合の2つの方法

既存のHaarのコードを動かし続けたいときの方法は2つです。

- **4系に留める**：`pip install "opencv-python<5"`で4系の最新（現時点では4.14.0.94）が入ります。版まで固定するなら`pip install opencv-python==4.14.0.94`です。4系は`cv2.data.haarcascades`のフォルダに`haarcascade_frontalface_default.xml`などが同梱されており、従来のコードがそのまま動きます。
- **5.0のcontrib版を使う**：`opencv-contrib-python`なら`CascadeClassifier`があります。ただし5.0.0.93の`cv2.data`フォルダにXMLは入っていないため、[opencv\_contribのxobjdetect/data/haarcascades](https://github.com/opencv/opencv%5Fcontrib/tree/5.x/modules/xobjdetect/data/haarcascades)からXMLを取得し、パスを直接渡します。

```
cascade = cv2.CascadeClassifier("haarcascade_frontalface_default.xml")
if cascade.empty():                              # パスを誤ると空のまま返る
    raise FileNotFoundError("カスケードXMLを読み込めません")
faces = cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5)
```

Haarは横顔・逆光・小さな顔に弱く、`minNeighbors`を上げれば誤検出は減る代わりに見逃しが増えます。Haarの調整で要件を満たせない場合は、YuNetへの移行を検討し、対象画像で検出率・誤検出率と処理時間を比較してください。新しく作る検出処理はYuNetから始め、Haarを残すのは既存システムの挙動を変えられない場合に限るべきです。

## 古いコードが動かないときの典型エラーと直し方

ネット上のOpenCVのコードは3系・4系の時代に書かれたものが多く、5.0では止まることがあります。エラーメッセージから原因を引けるように並べます（各項目の詳細は前の章で説明しています）。

| エラー                               | 原因                        | 直し方                         |
| --------------------------------- | ------------------------- | --------------------------- |
| not enough values to unpack       | findContoursの2値を3変数で受けている | contours, hierarchy の2値で受ける |
| no attribute ‘CascadeClassifier’  | 5.0の標準版                   | YuNetへ移行か4.14に固定            |
| no attribute ‘readNetFromCaffe’   | 5.0で削除                    | ONNXへ変換しreadNetFromONNX     |
| cvtColorで (-215:Assertion failed) | imreadがNoneを返した           | パスとNoneチェックを確認              |
| VideoWriterで何も保存されない              | コーデック非対応                  | isOpened()を確認しMJPG＋.aviへ    |

`findContours`は3系だけが`(image, contours, hierarchy)`の3値を返します。使っている版は`print(cv2.__version__)`で確かめられます。Caffeのモデルを使っている場合の移行先は[Caffeとは？開発が止まった深層学習フレームワークの現在地と移行先](/tech/details/3488/)でも触れています。ブラウザ上でOpenCVを動かしたい場合はPython版ではなく[OpenCV.jsの使い方｜CDN・npmでの導入からWebカメラ実装まで](/tech/details/3608/)の構成になります。

## よくある質問

### OpenCVの読み方は？

「オープンシーブイ」と読みます。Open Source Computer Vision Libraryの略です。Pythonのモジュール名`cv2`は、OpenCV 2系の時代に旧来の`cv`モジュールと区別するために付いた名前で、4系・5系でも`import cv2`のまま使います。

### OpenCVは商用利用でも無料ですか？

無料です。4.5.0以降はApache License 2.0、それより前は3条項BSDライセンスで、どちらも商用利用・改変・再配布を認めています。配布物に含める場合は、ライセンス文と著作権表示を残す条件があります。

### opencv-python（OpenCV）の最新バージョンは？

2026年10月時点のPyPI最新は5.0.0.93（2026-07-02公開）です。4系の最新は4.14.0.94（日本時間2026-07-29公開）で、5.0の後も更新されています。最新の版は[PyPIのリリース履歴](https://pypi.org/project/opencv-python/#history)で確認できます。

### pip install cv2 でエラーになるのはなぜ？

PyPIに`cv2`という名前のパッケージが無いためです。`cv2`はインストール後のモジュール名で、入れるパッケージは`opencv-python`です。サーバーなら`opencv-python-headless`を選びます。

### PillowとOpenCVはどちらを使うべき？

リサイズや形式変換、日本語の文字入れだけならPillowが手軽です。エッジ検出・輪郭抽出・動画・顔検出が必要ならOpenCVを選びます。`numpy.array(pil_image)`でPillowの画像を配列にすれば、OpenCVへ渡して併用できます（その場合はRGB→BGRの変換を挟みます）。

## 関連記事

- [Pillowとは？Pythonの画像処理ライブラリの使い方をコード付きで解説【12.3.0対応】](/tech/details/1343/)
- [エッジ検出とは？Canny法と微分フィルタの使い分けをOpenCVの実装で解説](/tech/details/16854/)
- [物体検出とは？仕組み・代表手法の比較から実装判断までエンジニア向けに解説](/tech/details/15323/)
- [NumPyとは？読み方・インストール・基本的な使い方をPythonで解説](/tech/details/3124/)
- [OCRとは？光学文字認識の仕組み・種類・精度と実装での組み込み方を解説](/tech/details/13582/)

---

出典: [OpenCVとは？Pythonでの使い方入門｜pip installから画像処理・顔検出まで【5.0対応】](<https://www.issoh.co.jp/tech/details/1344/>)（株式会社一創）