opencv-python-headless package relies on numpy below 2.3.0 ?

[wyatt-wong]

I installeed the pdf2docx package but found that it relies on opencv-python-headless package and the opencv-python-headless relies on the older numpy package below 2.3.0 ?

Can opencv-python-headless package update to support numpy > 2.3.0 ? The latest numpy package is 2.3.2 as at 04-Sep-2025.

[kvrban]

Same issue. I can not install picamera2 and opencv-python on my RPI 5 because of the issue.

[Shiv-Expert2503]

Testing Results: Python 3.10 vs 3.11 numpy Compatibility

I've tested the numpy version conflict across Python environments and found the root cause:

Python 3.10.18:

• numpy 2.3.2: ❌ Cannot install (requires Python ≥3.11)
• Final result: numpy 2.2.6 + opencv-python-headless 4.12.0.88 ✅

Python 3.11:

• numpy 2.3.2: ✅ Installs successfully initially
• But when installing pdf2docx: pip downgrades numpy 2.3.2 → 2.2.6
• Final result: numpy 2.2.6 + opencv-python-headless 4.12.0.88 ✅

Root Cause Identified:
The conflict occurs because opencv-python-headless restricts numpy<2.3.0, while newer packages (like pdf2docx) work best with numpy ≥2.3.0. Pip resolves this by downgrading numpy.

Proposed Solution:
Update opencv-python-headless to use conditional numpy requirements:

• Python <3.11: numpy>=1.17.2,<2.3.0 (current behavior)
• Python ≥3.11: numpy>=1.17.2,<2.4.0 (allow 2.3.x)

Next Steps:
I can test opencv functionality with numpy 2.3.x on Python 3.11+ and prepare a PR if maintainers are interested.

@wyatt-wong @kvrban - Does this match what you're experiencing? What Python versions are you using?

[wyatt-wong]

Testing Results: Python 3.10 vs 3.11 numpy Compatibility

I've tested the numpy version conflict across Python environments and found the root cause:

Python 3.10.18:

• numpy 2.3.2: ❌ Cannot install (requires Python ≥3.11)
• Final result: numpy 2.2.6 + opencv-python-headless 4.12.0.88 ✅

Python 3.11:

• numpy 2.3.2: ✅ Installs successfully initially
• But when installing pdf2docx: pip downgrades numpy 2.3.2 → 2.2.6
• Final result: numpy 2.2.6 + opencv-python-headless 4.12.0.88 ✅

Root Cause Identified:
The conflict occurs because opencv-python-headless restricts numpy<2.3.0, while newer packages (like pdf2docx) work best with numpy ≥2.3.0. Pip resolves this by downgrading numpy.

Proposed Solution:
Update opencv-python-headless to use conditional numpy requirements:

• Python <3.11: numpy>=1.17.2,<2.3.0 (current behavior)
• Python ≥3.11: numpy>=1.17.2,<2.4.0 (allow 2.3.x)

Next Steps:
I can test opencv functionality with numpy 2.3.x on Python 3.11+ and prepare a PR if maintainers are interested.

@wyatt-wong @kvrban - Does this match what you're experiencing? What Python versions are you using?

I am using Python 3.13.7, I already knew installed pdf2docx automatically downgrade numpy 2.26, that's why I raised this issue and see if the maintainer of opencv-python-headless can verify if it can works with numpy 2.3.2 and if so modify the requirements.txt file of opencv-python-headless accordingly. Or else update opencv-python-headless so that it is compatible to numpy 2.3.2

I have also installed numpy 2.3.2 using pip-review -a but i can't confirm if opencv-python-headless have any conflicts with numpy 2.3.2 or not.

Note further that according to the Python release notes, it is very likely that python 3.14 will come next after Python 3.13.7, which means python 3.13.7 could be the last maintenance release of python 3.13