pip tries to compile opencv-python and fails with 'Could not build wheels'
ERROR: Could not build wheels for opencv-python which use PEP 517 and cannot be installed directlyShort 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.
Fix it fast
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 --version2Match what you see, then jump to its fix
What does the error look like?
ERROR: Could not build wheels for opencv-python which use PEP 517 and cannot be installed directlyModuleNotFoundError: 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 --version2Fix
Upgrade pip inside the same environment, then install again.
python -m pip install --upgrade pip
python -m pip install opencv-python3Verify
The import works and prints a version.
python -c "import cv2; print(cv2.__version__)"Confirmed by raw.githubusercontent.com
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-python2Fix
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-headless3Verify
pip reports a wheel was downloaded, not built, and the import works.
python -c "import cv2; print(cv2.__version__)"Confirmed by pip.pypa.io
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix