System Information

• OpenCV python version 4.12.0.88
• MacOS 15.6.1
• Python 3.13.6

cv2's version.py in either a fresh venv or a fresh uv project (annotations are the same in the builds downloaded by either):

opencv_version = "4.12.0.88"
contrib = False
headless = False
rolling = False
ci_build = True

Detailed description

imread() and other functions work when supplied a pathlib.Path, as added in 4.10.0.84/#24773, but the type annotation is still just str.

For example, the annotations for imread() in __init__.pyi are:

@_typing.overload
def imread(filename: str, flags: int = ...) -> cv2.typing.MatLike | None: ...
@_typing.overload
def imread(filename: str, dst: cv2.typing.MatLike | None = ..., flags: int = ...) -> cv2.typing.MatLike | None: ...
@_typing.overload
def imread(filename: str, dst: UMat | None = ..., flags: int = ...) -> UMat | None: ...

All other functions taking in paths also appear to only be annotated for strings.

Steps to reproduce

Enable type checking in your IDE. Place an image in the same folder as your script at image.png and enter the code:

import cv2
from pathlib import Path

path = Path(__file__).resolve().parent

image = cv2.imread(path.joinpath("image.png"))
cv2.imwrite(path.joinpath("image copy.png"), image)

The type checker will have a problem with both the calls to cv2 — e.g. No overloads for "imwrite" match the provided arguments — but the script will successfully read image.png and write to a new file image copy.png.

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)