RuntimeError: _ARRAY_API is not PyCapsule object on Python 3.13 with no GIL

[CameronDevine]

System Information

• OpenCV 4.10.0
• Ubuntu 22.04
• Python 3.13 with no GIL
• Numpy 2.2.1

Detailed description

I am trying to build OpenCV with bindings using Python 3.13 with no GIL. I am able to build OpenCV, but when trying to import cv2 I get an error: RuntimeError: _ARRAY_API is not PyCapsule object.

Steps to reproduce

Build a docker container using the following dockerfile:

FROM nvidia/cuda:12.3.2-devel-ubuntu22.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update
RUN apt-get install -y software-properties-common
RUN add-apt-repository ppa:deadsnakes/ppa
RUN apt-get install -y cmake build-essential zip python3.13-nogil python3.13-dev

ADD https://bootstrap.pypa.io/get-pip.py /
RUN python3.13t /get-pip.py
RUN python3.13t -m pip install numpy

ADD https://github.com/opencv/opencv/archive/refs/tags/4.10.0.zip /opencv.zip
RUN unzip /opencv.zip
ADD https://github.com/opencv/opencv_contrib/archive/refs/tags/4.10.0.zip /opencv_contrib.zip
RUN unzip /opencv_contrib.zip

RUN mkdir build
RUN bash -c "cmake \
  -S /opencv-4.10.0 \
  -B /build \
  -DOPENCV_EXTRA_MODULES_PATH='/opencv_contrib-4.10.0/modules/cudev;/opencv_contrib-4.10.0/modules/cudaarithm;/opencv_contrib-4.10.0/modules/cudaimgproc;/opencv_contrib-4.10.0/modules/cudawarping' \
  -DBUILD_TESTS=OFF \
  -DBUILD_PERF_TESTS=OFF \
  -DBUILD_opencv_apps=OFF \
  -DWITH_OPENCL=OFF \
  -DWITH_PNG=OFF \
  -DWITH_JPEG=OFF \
  -DWITH_WEBP=OFF \
  -DWITH_OPENJPEG=OFF \
  -DWITH_JASPER=OFF \
  -DWITH_OPENEXR=OFF \
  -DWITH_JPEGXL=OFF \
  -DWITH_V4L=OFF \
  -DWITH_FFMPEG=OFF \
  -DWITH_GSTREAMER=OFF \
  -DWITH_ANDROID_MEDIANDK=OFF \
  -DVIDEOIO_ENABLE_PLUGINS=OFF \
  -DWITH_GTK=OFF \
  -DPARALLEL_ENABLE_PLUGINS=OFF \
  -DHIGHGUI_ENABLE_PLUGINS=OFF \
  -DWITH_PROTOBUF=OFF \
  -DBUILD_PROTOBUF=OFF \
  -DOPENCV_DNN_OPENCL=OFF \
  -DENABLE_CCACHE=OFF \
  -DBUILD_JAVA=OFF \
  -DBUILD_opencv_python2=OFF \
  -DBUILD_opencv_dnn=OFF \
  -DBUILD_opencv_gapi=OFF \
  -DBUILD_opencv_highgui=OFF \
  -DBUILD_opencv_flann=ON \
  -DBUILD_opencv_objdetect=OFF \
  -DBUILD_opencv_videoio=OFF \
  -DBUILD_opencv_video=OFF \
  -DBUILD_opencv_photo=OFF \
  -DBUILD_opencv_stitching=OFF \
  -DBUILD_opencv_world=OFF \
  -DBUILD_opencv_ml=OFF \
  -DBUILD_opencv_calib3d=OFF \
  -DBUILD_opencv_python3=ON \
  -DPYTHON_EXECUTABLE=$(which python3.13t) \
  -DOPENCV_PYTHON3_INSTALL_PATH=lib/python3.13t/dist-packages \
  -DPYTHON3_LIBRARIES=/usr/lib/x86_64-linux-gnu/libpython3.13t.so \
  -DWITH_CUDA=OFF 2>&1 \
    | tee /cmake.log"
RUN bash -c "make -C /build -j $(nproc) 2>&1 | tee /build.log"
RUN bash -c "make -C /build install 2>&1 | tee /install.log"

Then, inside the container run python3.13t -c "import cv2"

Issue submission checklist

• I report the issue, it's not a question
• I checked the problem with documentation, FAQ, open issues, forum.opencv.org, Stack Overflow, etc and have not found any solution
• I updated to the latest OpenCV version and the issue is still there
• There is reproducer code and related data files (videos, images, onnx, etc)

[opencv-alalek]

You need to take a look in direction of numpy build configuration first. Error message comes from there.

[asmorkalov]

Related: opencv/opencv-python#1029

[asmorkalov]

Related opencv/opencv-python#1051

[CameronDevine]

@asmorkalov I tried adding -DPYTHON3_LIMITED_API=OFF to my CMake command, but I am still getting the same error.

[CameronDevine]

@opencv-alalek, I opened an issue in the NumPy repository, but it seems like everything is pointing back towards this being an OpenCV issue. numpy/numpy#28138

[ngoldbaum]

Happy to answer questions about free-threading support. I did a lot of the work for NumPy.

[Vicky-45]

I was able to resolve this issue by building OpenCV from source with modifications to support Python 3.13’s free-threaded build. I adjusted the CMake configuration and made a few changes in the source code to ensure compatibility. After compiling, I tested it with some basic functions and it’s working as expected in the threaded environment.

This approach required careful adjustments, especially around the Python bindings and API usage, but it demonstrates that OpenCV can be made compatible with Python’s free-threaded mode with the right changes. I’m happy to share more details or assist others who want to experiment with this setup

[ngoldbaum]

I’m happy to share more details or assist others who want to experiment with this setup

Maybe open a draft pull request?

[nqhung]

This approach required careful adjustments, especially around the Python bindings and API usage, but it demonstrates that OpenCV can be made compatible with Python’s free-threaded mode with the right changes. I’m happy to share more details or assist others who want to experiment with this setup

I am struggling with using OpenCV for 13.3t, can you help me with this case? Thanks!