如何在setup.py中依赖opencv-python或opencv-python-headless？

在setup.py中实现可选依赖的方案 #

1. 额外依赖组（推荐） #

不在install_requires中默认指定任何OpenCV包，而是通过extras_require分场景提供可选依赖组，让用户根据自身环境选择安装：

from setuptools import setup

setup(
    # 你的包名、版本等基础配置
    name="your-package",
    version="0.1.0",
    # 其他配置...
    install_requires=[],  # 不强制默认安装OpenCV
    extras_require={
        "full": ["opencv-python"],          # 带GUI的开发环境用
        "headless": ["opencv-python-headless"],  # 无GUI服务器用
        "contrib-headless": ["opencv-contrib-python-headless"]  # 带contrib模块的无GUI版本
    }
)

用户安装时只需对应选择：

# 开发环境安装带GUI的版本
pip install your-package[full]
# 服务器安装headless版本
pip install your-package[headless]

同时建议在包的核心代码开头添加运行时检查，确保用户已安装至少一个符合要求的OpenCV包：

try:
    import cv2
except ImportError:
    raise ImportError("请安装以下任意一个OpenCV包：opencv-python、opencv-python-headless、opencv-contrib-python-headless")

2. 环境标记自动适配 #

如果想让安装过程根据环境自动选择依赖，可以利用setuptools的环境标记（environment markers），比如根据系统平台或环境变量判断：

setup(
    # 其他配置...
    install_requires=[
        # Windows/macOS默认安装带GUI的版本
        "opencv-python; sys_platform == 'win32' or sys_platform == 'darwin'",
        # Linux无DISPLAY环境默认安装headless版本
        "opencv-python-headless; sys_platform == 'linux' and not os.environ.get('DISPLAY')",
        # 允许用户通过环境变量指定安装contrib-headless版本
        "opencv-contrib-python-headless; os.environ.get('OPENCV_USE_CONTRIB') == '1'"
    ]
)

这种方式的局限性是环境判断可能不够精准，需要用户根据实际情况调整。

更换现代打包工具的方案 #

Poetry #

Poetry支持更灵活的依赖管理，通过pyproject.toml配置可选依赖组：

[tool.poetry]
name = "your-package"
version = "0.1.0"
description = ""
authors = ["Your Name <your.email@example.com>"]

[tool.poetry.dependencies]
python = "^3.8"
opencv-python = { version = "*", optional = true }
opencv-python-headless = { version = "*", optional = true }
opencv-contrib-python-headless = { version = "*", optional = true }

[tool.poetry.extras]
full = ["opencv-python"]
headless = ["opencv-python-headless"]
contrib-headless = ["opencv-contrib-python-headless"]

用户安装时通过-E参数指定依赖组：

poetry install your-package -E headless

Poetry会自动处理依赖冲突，避免同时安装多个OpenCV包。

Flit #

Flit同样支持通过pyproject.toml配置可选依赖，符合PEP规范：

[project]
name = "your-package"
version = "0.1.0"
authors = [{name = "Your Name", email = "your.email@example.com"}]

[project.optional-dependencies]
full = ["opencv-python"]
headless = ["opencv-python-headless"]
contrib-headless = ["opencv-contrib-python-headless"]

安装方式与setuptools一致：

pip install your-package[headless]

总结 #

• 基于setuptools的方案中，额外依赖组是最稳妥的方式，让用户自主选择适配环境的OpenCV包，避免强制安装导致的冲突；
• 现代打包工具（Poetry/Flit）的依赖管理更直观、规范，能更好地处理这类可选依赖场景，同时自动规避依赖冲突问题。

内容的提问来源于stack exchange，提问作者oliver