Resolving macOS, OpenCV, and Homebrew install errors

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.cmake file.

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:

1. There is no need to make this check…
2. …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.

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.cmake  file.

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!