opencv / opencv/opencv-python

Poor compatibility with Python 3.14+NumPy 2.3.3

Open
#1,201 6 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
5.4k
Forks
1k
Avg merge
22h 17m
Merged PRs (30d)
3

Description

This issue was raised last year, but the version involved was Py 3.10 and 3.11, so an additional issue is being proposed for compatibility with the new version.

Python 3.14.0 (tags/v3.14.0:ebf955d, Oct  7 2025, 10:15:03) [MSC v.1944 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import cv2

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.3.3 as it may crash. To support both 1.x and 2.x
versions of NumPy, modules must be compiled with NumPy 2.0.
Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.

If you are a user of the module, the easiest solution will be to
downgrade to 'numpy<2' or try to upgrade the affected module.
We expect that some modules will need time to support NumPy 2.

Traceback (most recent call last):  File "R:\Python314\Lib\_pyrepl\main.py", line 58, in interactive_console
    run_multiline_interactive_console(console)
  File "R:\Python314\Lib\_pyrepl\simple_interact.py", line 151, in run_multiline_interactive_console
    more = console.push(_strip_final_indent(statement), filename=input_name, _symbol="single")  # type: ignore[call-arg]
  File "R:\Python314\Lib\code.py", line 324, in push
    more = self.runsource(source, filename, symbol=_symbol)
  File "R:\Python314\Lib\_pyrepl\console.py", line 226, in runsource
    result = self.runcode(code)
  File "R:\Python314\Lib\_pyrepl\console.py", line 181, in runcode
    exec(code, self.locals)
  File "<python-input-0>", line 1, in <module>
    import cv2
  File "W:\cv2\__init__.py", line 181, in <module>
    bootstrap()
  File "W:\cv2\__init__.py", line 153, in bootstrap
    native_module = importlib.import_module("cv2")
  File "R:\Python314\Lib\importlib\__init__.py", line 88, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
AttributeError: _ARRAY_API not found
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    import cv2
  File "W:\cv2\__init__.py", line 181, in <module>
    bootstrap()
    ~~~~~~~~~^^
  File "W:\cv2\__init__.py", line 153, in bootstrap
    native_module = importlib.import_module("cv2")
  File "R:\Python314\Lib\importlib\__init__.py", line 88, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ImportError: numpy.core.multiarray failed to import
>>>

after downgraded to np1.26.4:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
opencv-contrib-python 4.13.0.90 requires numpy>=2; python_version >= "3.9", but you have numpy 1.26.4 which is incompatible.
opencv-python 4.13.0.90 requires numpy>=2; python_version >= "3.9", but you have numpy 1.26.4 which is incompatible.

(note:it requires numpy2 while installation, but numpy 1 during runtime
(WHAT THE F**K IS THIS???

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No repository files or tests are named. Start by reproducing the cv2 import with Python 3.14 and NumPy 2.3.3, then inspect the package build and dependency metadata for the generated wheel. Done means the package imports successfully and its declared NumPy requirements match runtime compatibility.

Written by the indexing model from the issue text.

Assessment

Tech stack
numpy, python
Domain
build-system
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.