Skip to content

Allow OpenCV 4.11 and NumPy 1.26 (GIF/AVIF still need OpenCV 4.12); bump to 0.4.1 - #16

Merged
MilkClouds merged 1 commit into
mainfrom
opencv-4.11-numpy-1
Oct 5, 2026
Merged

MilkClouds merged 1 commit into
mainfrom
opencv-4.11-numpy-1

Conversation

@MilkClouds

Copy link
Copy Markdown
Collaborator

0.4.0 requires opencv-python-headless>=4.12, and every 4.12+ wheel requires numpy>=2, so it forces NumPy 2 on all users. This PR lowers the floors to opencv-python-headless>=4.11 and numpy>=1.26. GIF and AVIF now raise an explicit error on OpenCV < 4.12 instead of blocking every image codec. Version 0.4.1. Nothing is tagged or published.

Measured (Linux x86_64, uv venvs, Python 3.10 and 3.12; NumPy 1.26.4, 2.0.2, latest 2.x)

Raw cv2.imdecodemulti / cv2.imencode:

4.10.0.84 4.11.0.86 4.12.0.88 / 5.0.0
JPEG, PNG, BMP, still WebP decode yes yes yes
Animated WebP decode no yes yes
GIF decode (still and animated) no no yes
AVIF decode no no yes
JPEG, PNG (RGB/RGBA) encode yes yes yes
Works with NumPy 1.26.4 / 2.0.2 / 2.2–2.5 yes / yes / yes yes / yes / yes needs NumPy 2 (4.12.0.88: <2.3)
  • With pytest --compare (TorchCodec 0.17.0) on 4.11, both NumPy 1.26.4 and 2.5.3, every JPEG/PNG/WebP/BMP test passes. The only failures are the 26 GIF/AVIF tests, and each fails with the new RuntimeError. On 5.0 all 154 pass.
  • 4.10 also fails the animated-WebP tests, so 4.11 is the floor.
  • An unconstrained install with numpy==1.26.4 resolves to OpenCV 4.11.0.86.

Changes

  • pyproject.toml: numpy>=1.26, opencv-python-headless>=4.11, version 0.4.1 and tensorcodec-av==0.4.1. Version also bumped in av/Cargo.toml, av/Cargo.lock and __init__.py.
  • _opencv.py: opencv(codec) still raises ImportError below 4.11. GIF and AVIF raise RuntimeError: GIF decoding requires OpenCV >= 4.12 (which requires NumPy >= 2), found 4.11.0. Nothing falls back silently.
  • Tests: on OpenCV < 4.12, the GIF/AVIF dispatch test expects that error. A new test fakes the 4.11/4.10 version strings to check both errors on any OpenCV.
  • CI: new test-without-av job with OpenCV 4.11.0.86 and NumPy 1.26.4 (macOS Intel, Python 3.10). The 4.12.0.88 job stays as the GIF/AVIF lower bound. The glibc 2.17 Python 3.10 validation installs numpy==1.26.4 opencv-python-headless==4.11.0.86 again; OpenCV is pinned so pip keeps NumPy 1.x.
  • Docs: docs/images.md (install and requirements), docs/releasing.md (version, minimum NumPy line) and the docs/system_ffmpeg.md example. README and docs/package_size.md never stated a NumPy 2 or OpenCV 4.12 requirement, so they are unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YAijSnAE4aAjuS1EcCTwqS

….4.1

Every opencv-python-headless 4.12+ wheel requires NumPy 2, so the 4.12 floor
forced NumPy 2 on all users. Measured on Python 3.10 and 3.12 with NumPy
1.26.4, 2.0.2 and latest 2.x: 4.11.0.86 decodes JPEG, PNG, BMP and still and
animated WebP and encodes JPEG/PNG, matching TorchCodec 0.17.0 as 4.12+
does; only GIF and AVIF are missing. 4.10.0.84 also cannot decode animated
WebP, so 4.11 is the floor.

The version check is now per codec: below 4.11 image codecs raise
ImportError; GIF and AVIF raise RuntimeError naming OpenCV 4.12 and its
NumPy 2 requirement. CI adds an OpenCV 4.11 + NumPy 1.26.4 job, and glibc
2.17 validation again installs NumPy 1.26.4 (with OpenCV 4.11 so pip keeps it).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YAijSnAE4aAjuS1EcCTwqS
@MilkClouds
MilkClouds merged commit 5c9c6a1 into main Oct 5, 2026
9 checks passed
@MilkClouds
MilkClouds deleted the opencv-4.11-numpy-1 branch October 5, 2026 01:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant