使用 pip 为 Python 安装 OpenCV#
本快速入门向大多数用户展示了在 Python 中获取 OpenCV 的推荐方式：通过 pip 从 PyPI 安装。本文还解释了虚拟环境、平台注意事项以及常见问题排查。如果您需要特定于操作系统的替代方案（系统软件包或源码构建），请参阅下方链接的操作系统页面，但对于典型的 Python 使用来说，这些是不需要的。
注意
某些版本可能是社区构建版或硬件供应商构建版，可能与官方版本有所不同。
快速入门#
# 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 的环境相匹配。
操作系统注意事项#
Linux: 您的默认 Python 可能是 python3。请使用 python3 -m venv .venv 和 python3 -m pip ...。如果您无法使用虚拟环境，pip --user 会安装到您的主目录：python3 -m pip install --user opencv-python。
Windows: 从 [python.org] 安装 Python 或通过 winget install Python.Python.3 安装。请确保勾选 “Add python to PATH”，或使用 IDE 中的 “Open in terminal”（在终端中打开），它会自动选择正确的解释器。
macOS: 使用系统自带的 python3 或管理版本（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 模块 + 无 GUI
每个环境请且仅安装上述 其中一个 包。
问题排查#
请首先阅读 opencv-python 项目的 README
Pip 尝试从源码构建 症状：构建步骤时间极长，出现 CMake 错误或编译器错误。解决方法：
升级构建工具：python -m pip install --upgrade pip setuptools wheel
确保您的 Python 版本被所选软件包支持。
如果您使用的是不常见的平台或 Python 构建版本，请切换到受支持的 Python 或尝试不同的变体（headless vs 非 headless）。
“No matching distribution found” 或 “Unsupported wheel”
确认您的 Python 版本（例如 python -V）。选择支持该版本的 wheel 包（PyPI 上的 manylinux/macOS/Windows wheels 针对特定的 Python 版本）。
使用主流 Python 版本（目前如 3.10–3.12）创建一个全新的虚拟环境并重新安装。
Raspberry Pi / ARM
Wheel 包的更新可能会滞后于新的 Python/Pi OS 版本。请先尝试 opencv-python-headless。如果不可用，请考虑使用系统软件包来提供摄像头/GUI 组件，或按照下方链接的操作系统页面从源码构建。
终端中导入成功但在 IDE 中失败
IDE 正在使用不同的解释器。请在 IDE 的解释器设置中选择与终端中相同的环境。
那么系统软件包或源码构建如何？#
对于使用 Python 的初学者，推荐使用 PyPI。原生分发软件包和完整的源码构建更适合有特定平台需求的进阶用户。您仍然可以在操作系统专属页面中找到它们，它们被移到了 “Alternatives”（替代方案）下方。
参阅#
OpenCV-Python 教程
操作系统页面：在 Windows 中安装 OpenCV-Python, 在 Ubuntu 中安装 OpenCV-Python, 在 Fedora 中安装 OpenCV-Python