【Python】InsightFaceのインストールと顔認識プログラムの作り方｜エラー対処・CPU対応コードまで完全ガイド

PythonでAIによる顔認識をやってみたい――そんなときに便利なのが、高精度な顔認識ライブラリInsightFaceです。この記事を読めば、InsightFaceのインストール → 画像から顔を検出して枠で囲むプログラムの作成 → 実行 → つまずいたときのエラー対処までを、一通りこなせるようになります。GPUがなくても動くCPU環境を基準に解説するので、手元のパソコンでそのまま試せます。

完成イメージ

InsightFaceのGitHubはこちら

InsightFaceとは？何ができるのか

InsightFaceは、深層学習（ディープラーニング）を使った顔認識のライブラリです。画像の中から「顔を見つける（顔検出）」「顔の特徴を数値化する（特徴抽出）」「誰の顔かを判定する（顔認識）」といったことが、少ないコードで実現できます。今回はその第一歩として、画像から顔を検出して、枠で囲むプログラムを作ります。

事前準備：実行環境

今回の動作環境は次のとおりです。InsightFaceやonnxruntimeは対応するPythonバージョンに少しシビアなので、新しすぎるバージョンは避け、安定して動く範囲を使うのが無難です。

• macOS（Windows・Linuxでも基本の流れは同じ）
• Python 3.10〜3.11 ＋ 仮想環境（venv）を推奨

Pythonのバージョンやプロジェクトを切り替えたい方は、別記事「【Python】pyenvとvenvの違いと併用方法｜バージョンとライブラリを両方きれいに管理する」を参考にしてください。

InsightFaceのインストール

まずpipを最新化し、必要なパッケージを入れます。CPUで動かすので、推論エンジンには onnxruntime（CPU版）を使います。

# pipとsetuptoolsを最新化
$ python -m pip install --upgrade pip setuptools

# 必要パッケージ（CPU環境）
$ pip install numpy opencv-python onnxruntime
$ pip install insightface

顔認識プログラムの作成

顔を検出したい画像（例として meeting_image.jpg）を、プログラムと同じフォルダに置いておきます。次のコードを image_recognition.py という名前で保存してください。

import cv2
import numpy as np
from insightface.app import FaceAnalysis

# FaceAnalysis（顔分析）オブジェクトを生成（CPUで実行）
# ※初回実行時に、顔認識モデル（buffalo_l）が自動でダウンロードされます
app = FaceAnalysis(providers=["CPUExecutionProvider"])
app.prepare(ctx_id=-1)   # CPUは -1、GPUを使う場合は 0 を指定

# 画像を読み込む
img = cv2.imread("meeting_image.jpg")

# 顔を検出する
faces = app.get(img)
print(f"検出された顔の数: {len(faces)}")

# 検出した顔を1つずつ、青い枠で囲む
for face in faces:
    x1, y1, x2, y2 = face.bbox.astype(np.int32)
    cv2.rectangle(img, (x1, y1), (x2, y2), (255, 0, 0), 7)

# 結果を output.jpg として保存する
cv2.imwrite("output.jpg", img)
print("output.jpg を保存しました")

ポイントを補足します。app.prepare(ctx_id=-1) の -1がCPU、0がGPUの指定です。ここを間違えると実行時にエラーになりやすいので注意してください。また face.bbox が、検出された顔の長方形（左上と右下の座標）です。これを cv2.rectangle に渡して枠を描いています。色の (255, 0, 0) は、OpenCVでは青を意味します。

使用する画像：meeting_image.jpg

顔検出で取得した変数facesの確認

プログラムの実行

保存したフォルダに移動して、次のコマンドで実行します。

$ python image_recognition.py

初回は顔認識モデルのダウンロードが走るため、少し時間がかかります（フリーズではありません）。完了すると、次のように表示され、同じフォルダに output.jpg が作成されます。

検出された顔の数: 5
output.jpg を保存しました

できあがった output.jpg を開くと、検出された顔が青い枠で囲まれているはずです。

うまくいかないときのエラー対処（トラブルシューティング）

InsightFaceは環境による相性が出やすいライブラリです。つまずきやすい代表例と対処をまとめます。

pip install insightface がビルドエラーで失敗する

古いバージョンや一部の環境では、インストール時にコンパイルが走って失敗することがあります。まずは pip install --upgrade insightface で最新版（ビルド不要で入りやすい）を試してください。それでも失敗する場合は、コンパイル環境を用意します。Macは xcode-select --install でコマンドラインツールを入れ、Windowsは「Visual C++ Build Tools」をインストール。加えて pip install cython を先に実行してから再挑戦してください。

実行時にモデルがダウンロードされず止まって見える

初回実行時は顔認識モデル（buffalo_l、数百MB）の自動ダウンロードが走ります。フリーズではないので、回線次第で数分待ちます。モデルは ~/.insightface/models/ に保存され、2回目以降はダウンロードされません。

CUDA / GPU 関連の警告やエラーが出る

GPUがないのにGPU指定になっていると起こります。CPUで動かすときは、FaceAnalysis(providers=["CPUExecutionProvider"]) とし、app.prepare(ctx_id=-1) を指定してください（本記事のコードはこの形です）。

ModuleNotFoundError: No module named ‘cv2’

OpenCVが入っていません。pip install opencv-python でインストールしてください。

顔が検出されない・数が少ない

小さい顔や低解像度の画像では検出を取りこぼすことがあります。app.prepare(ctx_id=-1, det_size=(640, 640)) のように検出サイズを指定すると改善する場合があります。画像のパスやファイル名の間違いがないかも確認してください。

例えるなら「写真から顔を探す“目”を借りる”」こと

InsightFaceがやっていることは、私たちが集合写真を見て「ここに人がいる、ここにもいる」と一人ひとりを指でなぞる作業に似ています。違うのは、その“目”がAIで、何万枚もの顔を見て学習済みだという点です。モデルはその学習済みの目、bboxは指でなぞった四角い枠、と考えると分かりやすいです。私たちはコードで「写真を渡して、見つけた顔の枠をちょうだい」とお願いしているだけなのです。

まとめ

• InsightFaceは、少ないコードで高精度な顔検出ができるPythonライブラリ
• CPUなら onnxruntime を入れ、providers=["CPUExecutionProvider"] ＋ ctx_id=-1 で動く
• 初回実行ではモデルが自動ダウンロードされる（フリーズではない）
• うまくいかないときは、ビルド環境・GPU指定・モデルDLの3点を確認

参考リソース

• InsightFace 公式GitHub（deepinsight/insightface）：本家のリポジトリと最新の使い方
• InsightFace Python Package README：FaceAnalysisの使用例・モデルパック一覧