As you undoubtedly know, configuring and installing OpenCV on your macOS machine can be a bit of a pain.
To help you and other PyImageSearch readers get OpenCV installed faster (and with less headaches), I put together a tutorial on using Homebrew to install OpenCV.
Using Homebrew allows you to skip manually configuring your build and compiling OpenCV from source.
Instead, you simply use what are called brew formulas which define how a given package should be automatically configured and installed, similar to how a package manager can intelligently install libraries and software on your system.
However, a bit of a problem arose a few weeks ago when it was discovered that there were some errors in the most recent Homebrew formula used to build and install OpenCV on macOS.
This formula caused two types of errors when building OpenCV on macOS via Homebrew:
- Error #1: A report that both Python 2 and Python 3 wrappers could not be built (this is not true, you can build both Python 2.7 and Python 3 bindings in the same Homebrew command).
- Error #2: A missing
downloader.cmakefile.
Myself, as well as PyImageSearch readers Andreas Linnarsson, Francis, and Patrick (see the comments section of the Homebrew OpenCV install post for the gory details) dove into the problem and tackled it head on.
Today I’m going to share our findings in hopes that it helps you and other PyImageSearch readers install OpenCV via Homebrew on your macOS machines.
In an ideal world these instructions will eventually become out of date as the Homebrew formula used to configure and install OpenCV is updated to correct these errors.
To learn more about resolving Homebrew errors when installing OpenCV, just keep reading.
Resolving macOS, OpenCV, and Homebrew install errors
In the remainder of this blog post I’ll discuss common errors you may run into when installing OpenCV via Homebrew on your macOS system.
I’ll also provide extra bonus suggestions regarding checking your Python version to help you debug these errors further.
Error #1: opencv3: Does not support building both Python 2 and 3 wrappers
Assuming you followed my original Homebrew + OpenCV install post, you may have ran into the following error when trying to install OpenCV:
$ brew install opencv3 --with-contrib --with-python3 --HEAD ... Error: opencv3: Does not support building both Python 2 and 3 wrappers
This error was introduced by the following commit. I find the error frustrating for two reasons:
- There is no need to make this check…
- …because Homebrew can be used to compile OpenCV twice: once for Python 2.7 and then again for Python 3.
To start, OpenCV 3 can be built with Python 2.7 and Python 3 bindings. It just requires two separate compiles.
The first compile handles building OpenCV 3 + Python 2.7 bindings while the second compile generates the OpenCV 3 + Python 3 bindings. Doing this installs OpenCV 3 properly while generating the correct cv2.so bindings for each respective Python version.
There are two ways to resolve this error, as discussed in this StackOverflow thread.
The first method is arguably simpler, but doesn’t address the real problem. Here we just update the brew install opencv3 command to indicate that we want to build OpenCV 3 without Python 3 bindings:
$ brew install opencv3 --with-contrib
Notice how we have left out the --with-python3 switch. In this case, Homebrew automatically builds Python 2.7 bindings for OpenCV 3 (there is no --with-python2 switch; it’s automatically assumed).
Similarly, if we wanted to build OpenCV 3 with Python 3 bindings, we would update the brew install opencv3 command to be:
$ brew install opencv3 --with-contrib --with-python3 --without-python
Here we supply --with-python3 to indicate we would like OpenCV 3 + Python 3 bindings to be generated, but to skip generating the OpenCV 3 + Python 2.7 bindings using the --without-python switch.
This method works; however, I find it both frustrating and confusing. To start, the --without-python switch is extremely ambiguous.
If I were to supply a switch named --without-python to an install command I would assume that it would build NO Python bindings what-so-ever, regardless of Python version. However, that’s not the case. Instead, --without-python really means no Python 2.7 bindings.
These switches are confusing to both OpenCV install veterans such as my myself along with novices who are just trying to get their development environment configured correctly for the first time.
In my opinion, a better solution (until a fix is fully released, of course) is to edit the OpenCV 3 install formula itself.
To edit the OpenCV 3 Homebrew install formula, execute the following command:
$ brew edit opencv3
And then find the following configuration block:
if build.with?("python3") && build.with?("python")
# Opencv3 Does not support building both Python 2 and 3 versions
odie "opencv3: Does not support building both Python 2 and 3 wrappers"
end
As you can see from my screenshot below, this configuration is on Lines 187-190 (however, these lines will change as the OpenCV 3 Homebrew formula is updated).
Once you’ve found this section, comment these four lines out:
#if build.with?("python3") && build.with?("python")
# # Opencv3 Does not support building both Python 2 and 3 versions
# odie "opencv3: Does not support building both Python 2 and 3 wrappers"
#end
I’ve provided a screenshot demonstrating commenting these lines out as well:
After you’ve commented the lines out, save and exit the editor to update the OpenCV 3 Homebrew install formula.
From there you should be able to successfully install OpenCV 3 via Homebrew using the following command:
$ brew install opencv3 --with-contrib --with-python3
Note: If you receive an error message related to downloader.cmake , make sure you proceed to the next section.
After OpenCV 3 has finished installing, go back to the original tutorial, and follow the instructions starting with the “Handling the Python 3 issue” section.
From there, you will have OpenCV 3 installed with both Python 2.7 and Python 3 bindings:
Again, keep in mind that two separate compiles were done in order to generate these bindings. The first compile generated the OpenCV 3 + Python 2.7 bindings while the second compile created the OpenCV 3 + Python 3 bindings.
Error #2: No such file or directory 3rdparty/ippicv/downloader.cmake
The second error you may encounter when installing OpenCV 3 via Homebrew is related to the downloader.cmake file. This error only occurs when you supply the --HEAD switch to the brew install opencv3 command.
The reason for this error is that the 3rdparty/ippicv/downloader.cmake file was removed from the repo; however, the Homebrew install formula has not been updated to reflect this (source).
Therefore, the easiest way to get around this error is to simply omit the --HEAD switch.
For example, if your previous OpenCV 3 + Homebrew install command was:
$ brew install opencv3 --with-contrib --with-python3 --HEAD
Simply update it to be:
$ brew install opencv3 --with-contrib --with-python3
Provided you’ve followed the instructions from the “Error #1” section above, Homebrew should now install OpenCV 3 with Python 2.7 and Python 3 bindings. You’ll now want to go back to the original Homebrew + OpenCV tutorial, and follow the instructions starting with the “Handling the Python 3 issue” section.
BONUS: Check your Python version and update paths accordingly
If you’re new to Unix environments and the command line (or if this is the first time you’ve worked with Python + OpenCV together), a common mistake I see novices make is forgetting to check their Python version number.
You can check your version of Python 2.7 using the following command:
$ python --version Python 2.7.13
Similarly, this command will give you your Python 3 version:
$ python3 --version Python 3.6.1
Why is this so important?
The original Homebrew + OpenCV install tutorial was written for Python 2.7 and Python 3.5. However, Python versions update. Python 3.6 has been officially released and is being used on many machines. In fact, if you were to install Python 3 via Homebrew (at the time of this writing), Python 3.6 would be installed.
This is important because you need to check your file paths.
For example, if I were to tell you to check the site-packages directory of your Python 3 install and provide an example command of:
$ ls /usr/local/opt/opencv3/lib/python3.5/site-packages/
You should first check your Python 3 version. The command executed above assumes Python 3.5. However, if after running python3 --version you find you are using Python 3.6, would need to update your path to be:
$ ls /usr/local/opt/opencv3/lib/python3.6/site-packages/
Notice how python3.5 was changed to python3.6 .
Forgetting to check and validate file paths is a common mistake that I see novices make when installing and configuring OpenCV with Python bindings.
Do not blindly copy and paste commands in your terminal. Instead, take the time to understand what they are doing so you can adapt the instructions to your own development environment.
In general, the instructions to install OpenCV + Python on a system do not change — but Python and OpenCV versions do change, therefore some file paths will change slightly. Normally all this amounts to changing one or two characters in a file path.
What's next? I recommend PyImageSearch University.
30+ total classes • 39h 44m video • Last updated: 12/2021
★★★★★ 4.84 (128 Ratings) • 3,000+ Students Enrolled
I strongly believe that if you had the right teacher you could master computer vision and deep learning.
Do you think learning computer vision and deep learning has to be time-consuming, overwhelming, and complicated? Or has to involve complex mathematics and equations? Or requires a degree in computer science?
That’s not the case.
All you need to master computer vision and deep learning is for someone to explain things to you in simple, intuitive terms. And that’s exactly what I do. My mission is to change education and how complex Artificial Intelligence topics are taught.
If you're serious about learning computer vision, your next stop should be PyImageSearch University, the most comprehensive computer vision, deep learning, and OpenCV course online today. Here you’ll learn how to successfully and confidently apply computer vision to your work, research, and projects. Join me in computer vision mastery.
Inside PyImageSearch University you'll find:
- ✓ 30+ courses on essential computer vision, deep learning, and OpenCV topics
- ✓ 30+ Certificates of Completion
- ✓ 39h 44m on-demand video
- ✓ Brand new courses released every month, ensuring you can keep up with state-of-the-art techniques
- ✓ Pre-configured Jupyter Notebooks in Google Colab
- ✓ Run all code examples in your web browser — works on Windows, macOS, and Linux (no dev environment configuration required!)
- ✓ Access to centralized code repos for all 500+ tutorials on PyImageSearch
- ✓ Easy one-click downloads for code, datasets, pre-trained models, etc.
- ✓ Access on mobile, laptop, desktop, etc.
Summary
In today’s blog post we reviewed two common error messages you may encounter when installing OpenCV 3 via Homebrew:
- Error #1: A report that both Python 2 and Python 3 wrappers could not be built.
- Error #2: A missing
downloader.cmakefile.
I then provided solutions to each of these errors thanks to the help of PyImageSearch readers Andreas Linnarsson, Francis, and Patrick.
I hope these instructions help you avoid these common errors when installing OpenCV 3 via Homebrew on your macOS machine!
Before you go, be sure to enter your email address in the form below to be notified when future blog posts are published on PyImageSearch!
Join the PyImageSearch Newsletter and Grab My FREE 17-page Resource Guide PDF
Enter your email address below to join the PyImageSearch Newsletter and download my FREE 17-page Resource Guide PDF on Computer Vision, OpenCV, and Deep Learning.
Its sad that the hardest part about learning OpenCV is installing the damn thing!
You are quite right, Ryan!
I was thinking the same. But finally – I was able to manage it and got it working. Thanks to this awesome post.
If you’re installing from scratch you may encounter an issue where the site packages for your virtual environment do not work. You can tell this is the case if things work fine outside of the virtual environment (you can perform an import cv2 without issues), but it fails from within the virtual environment.
If this is the case you may have to tell the virtual environment to use the site packages with the toggleglobalsitepackages command. For example if you have an environment called ‘cv3’ you can enable the site packages with:
toggleglobalsitepackages cv3
(cv3) AMacHasNoName:cvTest gpierce$ toggleglobalsitepackages cv3
Enabled global site-packages
Hi Greg, thanks for the comment. Although I wouldn’t suggest enabling global site-packages as that can defeat the purpose of Python virtual environments in the first place (since the goal is to keep packages sequestered and independent from each other for each project).
Instead, I would recommend that you sym-link your
cv2.sobindings into your Python virtual environment rather than trying to toggle the global site-packages.I don’t totally disagree, but manually sim-linking bindings across environments felt even worst to me than flipping the global bit. If I have to symlink libraries to get things to work consistently, there is a lot less value in having the virtual environment.
Hi Greg — if your browse your system install packages (especially if you’ve ever updated a Unix machine) you’ll know that sym-links are generated to point to the latest version of a particular library on your system. It may seem like a “hack” but sym-links are an important aspect of Unix machines running efficiently. Similarly, there is nothing wrong with using a sym-link in a virtual environment to keep your environments independent.
In either case, I’m happy that you found a workflow that works for you!
I feel like I’m extremely close to installing openCV.
I received the statement “This formula is keg-only, which means it was not symlinked into /usr/local, because opencv3 and opencv install many of the same files..”
And tried to follow your recommended solution, but it looks like I don’t have the folder
/usr/local/opt/opencv3/lib/python3.5/site-packages/
I was able to navigate to /usr/local/opt/opencv3/lib , but I don’t have a python folder of any sort within that path. Do you know what the problem could be?
Hi Cade — it sounds like you did not install Python 2.7 or Python 3 via Homebrew.
Did you forget to run:
This can happen if you didn’t install numpy via homebrew. If this is the case, remove your existing version of numpy and install it via homebrew. Then try installing openCV
Oh hey, just noticed you mentioned me after the comments in the last post 🙂 thanks for pulling this together, I’ve just now finally been able to get it installed and working (ended up also having to run brew update-reset to make it work before trying brew install opencv3 –without-python –with-python3 because of whatever I had done before).
I’ve been using opencv off and on for the past 5 years or so, and seems every time I come back to it I need to install it on some platform or another.. and the issues at that time are always a head-scratcher and unique to that 2-month period of time heh. Let me just tell you about the hoops I had to go through getting it installed on an intel edison chip… none of which I’m sure are valid now
Hey Patrick — it was with your help that I was able to get this updated blog post out 🙂 Thank you again.
Great install tutorial! Found it very helpful with the Python 2 + Python 3… One issue I’m having is with cv2.imshow() and cv2.waitKey() – neither of these work in Mac OS (Sierra) for me and it appears as if it’s a problem for many people.
Are you able to get this working on a Macbook Pro?
This is an issue with the latest commit of OpenCV in the GitHub repository. Simply remove the
--HEADswitch from your Homebrew command and it will resolve the issue.I installed OpenCV 3 using pip on my Mac:
pip install opencv-python opencv-python-contrib
It does have some limitations, but mostly everything is working. cv2.imshow doesn’t work, but there’s a simple solution, I can use pillow or matplotlib instead to show the images and it works great. I do either:
import matplotlib.pyplot as plt
plt.imshow(img)
plt.show()
or
from PIL import Image
Image.fromarray(img).show()
The nice thing about pillow is that is uses Mac’s native Preview.
Wish me luck. I’m going to install openCV for python 2.7 and python 3.6 and java bindings. I really appreciate these blog posts and instructions.
Best of luck Eric!
Hi! I’m pretty new to python, terminal, and opencv. I was not able to edit the opencv formula (the hashtags just didn’t stick in terminal when i tried to add them) so I tried to do the two separate installations using t –without python –with python3. I did this for python2 first, but when the opencv installation finished and i tried to install it with python3 bindings, I got this message:
$ brew install opencv3 –with-contrib –with-python3 –without-python
Warning: homebrew/science/opencv3 3.2.0 is already installed
And I can’t go any farther. How should I proceed to get python3 bindings linked?
Hey Alex. By default Brew uses the “vim” editor for any edits you want to make. In order to comment out those 4 lines, press “i” to enter insert mode. Any key your press should then appear before the cursor and it will behave like a normal editor. When you are finished editing, press esc to exit insert mode. To save the file press esc again to enter command mode (window will flash). Once in command mode type “:wq!” and press enter to execute a write and quit. To be sure the changes took, run “brew edit opencv3” again and make sure the lines are still commented out. Good luck!
p.s. If you’re still having trouble, uncomment out the lines and try
brew install opencv3 --with-contrib --with-python3 --without-python --HEADHello!
Some time ago the Homebrew team decided to rename opencv3 to opencv and the former opencv to opencv@2. They also migrated the formula to homebrew/core and at the same time removed a lot of the build options we are used to.
By default it will now install bindings for both python version 2 and 3 as well as eigen, ffmpeg, libpng, libtiff, openexr and numpy. If any of the python versions are missing it will install that too.
So all you have to do is to run (you might have to tap homebrew/core before that):
brew install opencv
This will create python2 cv2.so object as well as the python3 cv2.cpython-36m-darwin.so cv2.so object as being described earlier.
Good luck!
Sadly the simplified formula now has no Cuda support option.
Hi Paul — Homebrew is nice but if you want full control over the compile I would recommend compiling OpenCV from source. I have a number of tutorials that discuss how to compile and install OpenCV. You can find them here.
Hi, I’ve installed everything on my mac but I keep getting clang error: linker command problems. Apparently kernel framework not found? Can you help me with this?
HI- The only way I was able to use both python and python3 on my mac was to keep PYTHONPATH as it was (ie, pointing to python2.7/site_packages) and then to alias python3 in my .zshrc startup file as follows:
alias python3=’PYTHONPATH=/usr/local/lib/python3.6/site-packages; python’
now both python and python3 see cv2.so. I suppose there will be gotchas if I try to use python virtual environments. Any advice on the long term? Should I give up the ability to use both 2 and 3 from the command line and always use virtual environments for python3 use.
I would highly recommend that you use Python virtual environments for both Python 2.7 and Python 3.
Hi Adrian ,
In Jupyter whenever I am running imshow command display window getting freezes. any suggestion or solution?
You cannot use cv2.imshow with Jupyter. Use “plt.imshow” from matplotlib instead.
When attempting to execute the brew install opencv3 –with-contrib –with-python3 command, the following error occurs: Error: invalid option: –with-contrib.
Does anyone know how to solve this error?
Have you tried following my latest OpenCV 4 and macOS install guide? Give it a try and see if it resolves the problem for you.
Could you resolve this issue? I am also facing the same issue.
I am running $ brew install opencv3 –with-contrib –with-python3 –HEAD
I am hitting the error Error: invalid option: –with-contrib
What can we do for this, what does –with-contrib does
I recommend you follow this updated macOS + OpenCV install guide instead.