このクイックスタートでは、ほとんどのユーザがPythonでOpenCVを導入するための推奨方法を示す。pip を使って PyPI からインストールする。仮想環境、プラットフォームに関する注意点、よくあるトラブルシューティングについても説明する。OS固有の代替手段（システムパッケージやソースビルド）が必要な場合は、以下にリンクしたOSのページを参照すること。ただし、一般的なPythonの利用ではこれらは必須ではない。

覚え書き: ：OpenCVチームは PyPI パッケージのみを保守している。Condaディストリビューションやプラットフォーム固有のビルドはコミュニティビルドやハードウェアベンダのビルドであり、公式のものとは異なる場合がある。

クイックスタート

# 1) Create and activate a virtual environment (recommended)
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
 
# 2) Upgrade pip tooling
python -m pip install --upgrade pip setuptools wheel
 
# 3) Install OpenCV from PyPI (choose ONE)
pip install opencv-python          # main package (most users)
# or
pip install opencv-contrib-python  # + extra modules (contrib)
# or
pip install opencv-python-headless # no GUI/backends (servers/CI)
# or
pip install opencv-contrib-python-headless # no GUI/backends with extra modules (servers/CI)

小さなhello‑world

import cv2 as cv
import numpy as np
 
print("OpenCV:", cv.__version__)
img = np.zeros((120, 400, 3), dtype=np.uint8)
cv.putText(img, "OpenCV OK", (10, 80), cv.FONT_HERSHEY_SIMPLEX, 2, (255,255,255), 3)
# If you installed a non-headless build, you can display a window:
# cv.imshow("hello", img); cv.waitKey(0)
# Always safe (headless or not): save to file
cv.imwrite("hello.png", img)

仮想環境とIDE

仮想環境を使うと、プロジェクトの依存関係を分離して管理できる。環境を作成または有効化するツールには次のものがある。

venv（組み込み）および virtualenv
Conda環境
ワークスペースごとに環境を自動作成・自動有効化するIDE（VS Code、PyCharm）

IDE内でインポートが失敗する場合は、IDEが選択しているインタプリタが、OpenCVをインストールした環境と一致しているか確認すること。

OSに関する注意

Linux: デフォルトのPythonが python3 である場合がある。python3 -m venv .venv と python3 -m pip ... を使うこと。仮想環境を使えない場合、pip --user でホームディレクトリにインストールできる：python3 -m pip install --user opencv-python。
Windows: [python.org] から、または winget install Python.Python.3 経由でPythonをインストールする。「Add python to PATH」が有効になっていることを確認するか、IDEから 「Open in terminal」 を使うこと。これにより正しいインタプリタが自動的に選択される。
macOS: システムの python3 または管理されたPython（HomebrewやPython.org）を使う。常に仮想環境を優先すること。
Raspberry Pi / ARMボード: 一部のPi OSとPythonの組み合わせでは、ビルド済みのwheelが存在しない場合がある。以下のトラブルシューティングを参照すること。

PyPIのバリアントを選ぶ

opencv-python：GUI/バックエンドを含むOpenCVのコアモジュール
opencv-contrib-python：コアに加えて contrib モジュールを含む
opencv-python-headless：GUI/バックエンドなし（サーバ/コンテナ/CIに最適）
opencv-contrib-python-headless：contrib + ヘッドレス

環境ごとに、これらのうち1つだけをインストールすること。

トラブルシューティング

まずopencv-pythonプロジェクトの README から始めること

pipがソースからビルドしようとする 症状：非常に長いビルドステップ、CMakeエラー、コンパイラエラー。対処法：

ビルドツールをアップグレードする：python -m pip install --upgrade pip setuptools wheel
選択したパッケージが、使用しているPythonのバージョンをサポートしているか確認すること。
一般的でないプラットフォームやPythonビルドを使っている場合は、サポートされているPythonに切り替えるか、別のバリアント（ヘッドレスか非ヘッドレスか）を試すこと。

「No matching distribution found」または「Unsupported wheel」

Pythonのバージョンを確認する（例：python -V）。そのバージョンをサポートするwheelを選ぶこと（PyPI上のmanylinux/macOS/Windowsのwheelは特定のPythonバージョンを対象としている）。
主流のPython（例：現時点では3.10〜3.12）で新しい仮想環境を作成し、再インストールすること。

Raspberry Pi / ARM

wheelは新しいPython/Pi OSのリリースに遅れることがある。まず opencv-python-headless を試すこと。利用できない場合は、カメラ/GUI部分についてはシステムパッケージを検討するか、以下にリンクしたOSページに従ってソースからビルドすること。

ターミナルではインポートできるがIDEでは失敗する

IDEが別のインタプリタを使っている。IDEのインタプリタ設定で同じ環境を選択すること。

システムパッケージやソースからのビルドについては？

Pythonを使う初心者には、PyPIが推奨される。ネイティブのディストリビューションパッケージや完全なソースビルドは、プラットフォーム固有のニーズを持つ上級者に適している。これらは「Alternatives」の下に移動され、OS固有のページで引き続き見つけることができる。