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で解説で確認できます。

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

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

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

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

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

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

PillowとOpenCVの使い分け

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

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

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

Pythonでは公式のビルド済みパッケージをpipで入れます。使用環境に対応するwheelがあれば、ソースからのビルドは不要です。PyPIの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つ入れると後から入れた方が上書きし、関数が見つからない不具合の原因になります。

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のリリース一覧でも4.14.0は2026-07-19、5.0.0は2026-06-06）。判断の基準は、動かしたいコードが5.0で消えた機能を使っているかどうかです。

公式のOpenCV 4から5への移行ガイドによると、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の実装で解説で掘り下げています。

二値化と輪郭抽出：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の実装で解説を参照してください。

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

動画・カメラを処理する：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）で人を検知して録画するまでで扱っています。

処理結果の動画保存：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で配布されています。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で読む構成になります。手法の比較は物体検出とは？仕組み・代表手法の比較から実装判断までエンジニア向けに解説にまとめています。検出モデルの学習データ作りから現場の検査工程への組み込みまでを任せたい場合は、画像認識AIモデル構築の支援もご相談いただけます。

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から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では止まることがあります。エラーメッセージから原因を引けるように並べます（各項目の詳細は前の章で説明しています）。

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

よくある質問

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のリリース履歴で確認できます。

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対応】
• エッジ検出とは？Canny法と微分フィルタの使い分けをOpenCVの実装で解説
• 物体検出とは？仕組み・代表手法の比較から実装判断までエンジニア向けに解説
• NumPyとは？読み方・インストール・基本的な使い方をPythonで解説
• OCRとは？光学文字認識の仕組み・種類・精度と実装での組み込み方を解説