Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pip tries to compile opencv-python and fails with 'Could not build wheels'

ErrorERROR: Could not build wheels for opencv-python which use PEP 517 and cannot be installed directly

Short answer

pip only compiles opencv-python when it cannot find a ready-made wheel it accepts. The two usual reasons are a pip older than 19.3, which cannot read the package's build settings, and a Python or Linux that has no matching wheel. Upgrade pip first; then ask pip for wheels only to see the real reason.

  • Applies to pip 25, Python 3.12, opencv-python 4.x, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the pip and Python versions in use. The project says pip 19.3 is the minimum, and the Python that runs pip decides which wheels exist.

    python -m pip --version
    python --version
  2. 2Match what you see, then jump to its fix

    1. 1ModuleNotFoundError: No module named 'skbuild' during the buildpip is too old to build or pick the packageFix
    2. 2pip prints 'Building wheel for opencv-python' and runs for a long time before failingNo wheel matches this Python or Linux, so pip falls back to the source packageFix

What does the error look like?

  • ERROR: Could not build wheels for opencv-python which use PEP 517 and cannot be installed directly
  • ModuleNotFoundError: No module named 'skbuild'

Cause 1 of 2

pip is too old to build or pick the package

1Check

The opencv-python README says the pip version must be 19.3 or newer. Anything older, often the pip shipped with an old distro or a small Docker image, fails this way.

python -m pip --version

2Fix

Upgrade pip inside the same environment, then install again.

python -m pip install --upgrade pip
python -m pip install opencv-python

3Verify

The import works and prints a version.

python -c "import cv2; print(cv2.__version__)"

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 2

No wheel matches this Python or Linux, so pip falls back to the source package

1Check

A wheel install is quick and downloads a .whl file. If pip builds instead, no wheel was accepted. The project builds its Linux wheels as manylinux2014 and dropped older distributions from 4.3.0, so a very old OS or an unusual platform lands here. With --only-binary pip refuses source packages, so it stops instead of compiling and you see that no wheel was found.

python -m pip install --only-binary :all: opencv-python

2Fix

Use a supported base: a current Python and a current Linux image. If you do not need windows from cv2, the headless wheel has no GUI code and is smaller. Only compile from source on purpose, using the documented build variables.

python -m pip install --upgrade pip
python -m pip install opencv-python-headless

3Verify

pip reports a wheel was downloaded, not built, and the import works.

python -c "import cv2; print(cv2.__version__)"

Confirmed by pip.pypa.io

Did this fix it?

How do I stop it coming back?

  • Upgrade pip as the first line of every Dockerfile and CI job that installs Python packages.
  • Pin the opencv-python version in requirements.txt so a build does not change under you.
  • Install only one of the four opencv packages in a given environment.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.