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
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
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
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/
python3.5 was changed to
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? We recommend PyImageSearch University.
84 total classes • 114+ hours of on-demand code walkthrough videos • Last updated: February 2024
★★★★★ 4.84 (128 Ratings) • 16,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:
- ✓ 84 courses on essential computer vision, deep learning, and OpenCV topics
- ✓ 84 Certificates of Completion
- ✓ 114+ hours of on-demand video
- ✓ Brand new courses released regularly, 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 536+ tutorials on PyImageSearch
- ✓ Easy one-click downloads for code, datasets, pre-trained models, etc.
- ✓ Access on mobile, laptop, desktop, etc.
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
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.