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

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.

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

@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?

@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 (pip-review) 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

This is now also preventing the usage of Python 3.14 which needs the newest Numpy, please update!

This is now also preventing the usage of Python 3.14 which needs the newest Numpy, please update!

#1142 was just approved

Esto ahora también impide el uso de Python 3.14, que necesita la versión más nueva de Numpy. ¡Actualice!

#1142 acaba de ser aprobado

#1135 (comment)

I'm on Apple Silicon and other packages that my project uses are happy with the latest numpy. I use python 3.13 .

opencv-python 4.12.0.88 requires numpy<2.3.0,>=2; python_version >= "3.9", but you have numpy 2.3.5 which is incompatible.

What are the plans for moving to the latest numpy branch?

When installing opencv-python with python3.14 (in my case under linux) it currently installs numpy2.2.6 by default. However, python3.14 does not support numpy2.2.x, leading to serious memory corruption issues (see numpy/numpy#30626 (comment), numpy/numpy#28681).
The clash creates wide-spread problems when dealing with large data, making it hard to have proper workflows (using numpy, matplotlib,...) in this config.
E.g.,a simple np.histogram does not work for large arrays (longer than 2**15).

>>> import numpy 

>>> numpy.histogram(numpy.random.rand(10000))
(array([3189, 3188, 3355, 3262, 3306, 3263, 3258, 3304, 3350, 3292]), array([3.65694354e-05, 1.00026379e-01, 2.00016189e-01, 3.00005999e-01,
       3.99995808e-01, 4.99985618e-01, 5.99975428e-01, 6.99965238e-01,
       7.99955047e-01, 8.99944857e-01, 9.99934667e-01]))
>>> numpy.histogram(numpy.random.rand(2**15))
Traceback (most recent call last):
  File "<python-input-14>", line 1, in <module>
    numpy.histogram(numpy.random.rand(100000))
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../lib64/python3.14/site-packages/numpy/lib/_histograms_impl.py", line 876, in histogram
    n += np.bincount(indices, weights=tmp_w,
                     minlength=n_equal_bins).astype(ntype)
ValueError: operands could not be broadcast together with shapes (10,) (12,) (10,)

So yes, please update! :-)

It's been a while and I have already updated to Python 3.14.2

What is the timeline for the next release?

Version 4.13.0.90 was released yesterday which now depend on numpy >= 2.

Navigation Menu

Repository navigation

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

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Activity

kvrban commented on Sep 9, 2025

Shiv-Expert2503 commented on Sep 14, 2025

wyatt-wong commented on Sep 14, 2025

Houbein commented on Sep 21, 2025

vfazio commented on Sep 21, 2025

faverl commented on Oct 26, 2025

jrp2014 commented on Dec 7, 2025

BKriener commented on Jan 13, 2026

wyatt-wong commented on Jan 13, 2026

mhicks-cfs commented on Jan 16, 2026

Tenzer commented on Jan 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions