`pip install inference` installs three OpenCV distributions; `easyocr` pulls an unpinned `opencv-python-headless` 5.0 that competes with the pinned 4.x `cv2`

Open
  • Is something wrong?
#3,174 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
backend, databases

Research direction

Start with requirements/_requirements.txt, inference_models/pyproject.toml, and the existing requirements/requirements.easyocr.txt; compare how OpenCV dependencies are declared and inspect the install paths described in the issue. Reproduce with the Python 3.13 virtual environment commands in the report. Done means the chosen dependency arrangement prevents an unpinned opencv-python-headless release from overriding the supported OpenCV version in a clean install.

Written by the indexing model from the issue text.

Description

What happens

A clean pip install inference (1.7.4, Python 3.13, macOS arm64; same with uv pip install) ends up with three distributions that all own cv2/:

opencv-python           4.11.0.86   <- inference, inference-sdk, inference-models, roboflow-workflows (pinned <4.13 / <=4.13.0)
opencv-contrib-python   4.11.0.86   <- inference (requirements/_requirements.txt, pinned <4.13)
opencv-python-headless  5.0.0.93    <- easyocr 1.7.2 <- inference-models (core dependency, unpinned)

pip/uv treat them as unrelated packages, so all three install and the last one to unpack wins the cv2/ directory. Which one that is depends on resolver and install order:

  • uv pip install inference: import cv2 gives 4.11.0 (the pinned build happened to unpack last).
  • python -m pip install inference: import cv2 gives 4.12.0 (same).

So a fresh install currently lands on the pinned 4.x build by luck of ordering. Any later operation that reinstalls headless flips it. For example, after the pip install above:

$ pip install --force-reinstall --no-deps opencv-python-headless==5.0.0.93   # what `pip install -U easyocr` would do
$ python -c "import cv2; print(cv2.__version__)"
5.0.0
$ pip check
No broken requirements found.

import cv2 now returns the headless 5.0 build, the opencv-python<4.13.0 pin added in #2357 (tensor-native Workflows) is silently defeated, and nothing in pip reports a problem because the three distributions are unrelated as far as metadata goes.

Why

inference_models/pyproject.toml lists easyocr~=1.7.2 as a core dependency (since the inference-exp → inference-models rename, 927d6dd24). easyocr depends on opencv-python-headless with no version bound, so it resolves to the newest release, which has been 5.0.0.93 since 2026-07-02.

The repo already recognises this class of problem: requirements/requirements.magevl.txt is installed with --no-deps precisely because "installing headless alongside the opencv-python this repo already pins puts two packages behind cv2", and the Jetson Dockerfiles override opencv-python-headless==4.12.0.88 (#1045). Neither applies to the PyPI install path through inference-models.

Reproduction
python3.13 -m venv v && v/bin/pip install inference
v/bin/pip list | grep -i opencv
v/bin/python -c "import cv2; print(cv2.__version__, hasattr(cv2, 'imshow'))"
Options
  1. Add opencv-python-headless>=4.8.1.78,<4.13.0 next to the existing opencv-python/opencv-contrib-python pins in requirements/_requirements.txt and inference_models/pyproject.toml, so whichever package wins cv2/ is at least a supported 4.x build. Smallest change; keeps three packages installed.
  2. Make easyocr an optional extra of inference-models (it already has requirements/requirements.easyocr.txt on the inference side), so the default install stops pulling headless at all.
  3. Both.

Happy to open a PR for whichever you prefer.

Dominant language
Python
Stars
2.5k
Forks
340
Avg merge
2d 11h
Merged PRs (30d)
92

Getting set up

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.

More from roboflow/inference

All issues in roboflow/inference

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.