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:

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  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:

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:

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:

And then find the following configuration block:

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).

Figure 1: Finding the Homebrew + OpenCV 3 formula that needs to be edited.

Once you’ve found this section, comment these four lines out:

I’ve provided a screenshot demonstrating commenting these lines out as well:

Figure 2: Updating the Homebrew + OpenCV 3 install formula to resolve the error.

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:

Figure 3: Successfully compiling OpenCV 3 with Python 2.7 and Python 3 bindings on macOS via Homebrew.

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:

Figure 4: Importing the cv2 library into a Python 2.7 and Python 3 shell.

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:

Simply update it to be:

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:

Similarly, this command will give you your Python 3 version:

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:

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:

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 slightlyNormally all this amounts to changing one or two characters in a file path.


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!

, , , , , ,

32 Responses to Resolving macOS, OpenCV, and Homebrew install errors

  1. Ryan Rife May 15, 2017 at 11:26 am #

    Its sad that the hardest part about learning OpenCV is installing the damn thing!

    • Adrian Rosebrock May 15, 2017 at 6:35 pm #

      You are quite right, Ryan!

    • Falko May 17, 2017 at 4:14 am #

      I was thinking the same. But finally – I was able to manage it and got it working. Thanks to this awesome post.

  2. Greg Pierce May 15, 2017 at 2:48 pm #

    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

    • Adrian Rosebrock May 15, 2017 at 6:37 pm #

      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 bindings into your Python virtual environment rather than trying to toggle the global site-packages.

      • Greg Pierce May 19, 2017 at 11:59 pm #

        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.

        • Adrian Rosebrock May 21, 2017 at 5:16 am #

          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!

  3. Cade Zacharias June 6, 2017 at 3:49 pm #

    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

    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?

    • Adrian Rosebrock June 9, 2017 at 1:58 pm #

      Hi Cade — it sounds like you did not install Python 2.7 or Python 3 via Homebrew.

      Did you forget to run:

    • Chatura June 24, 2017 at 5:10 am #

      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

  4. Patrick June 14, 2017 at 10:18 pm #

    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

    • Adrian Rosebrock June 16, 2017 at 11:24 am #

      Hey Patrick — it was with your help that I was able to get this updated blog post out 🙂 Thank you again.

  5. Scott June 22, 2017 at 10:29 am #

    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?

    • Adrian Rosebrock June 27, 2017 at 6:50 am #

      This is an issue with the latest commit of OpenCV in the GitHub repository. Simply remove the --HEAD switch from your Homebrew command and it will resolve the issue.

  6. Andrew July 11, 2017 at 3:23 pm #

    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



    from PIL import Image

    The nice thing about pillow is that is uses Mac’s native Preview.

  7. Eric Palmer July 15, 2017 at 11:16 am #

    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.

    • Adrian Rosebrock July 18, 2017 at 10:07 am #

      Best of luck Eric!

  8. Alex July 20, 2017 at 11:09 am #

    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?

    • Drew July 21, 2017 at 10:17 am #

      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 --HEAD

    • Andreas Linnarsson September 10, 2017 at 9:50 am #


      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 object as well as the python3 object as being described earlier.

      Good luck!

      • Paul Mison December 1, 2017 at 6:57 pm #

        Sadly the simplified formula now has no Cuda support option.

        • Adrian Rosebrock December 2, 2017 at 7:20 am #

          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.

  9. Ahmad Abdillah September 14, 2017 at 7:29 am #

    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?

  10. stephen wright September 19, 2017 at 10:45 pm #

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

    • Adrian Rosebrock September 20, 2017 at 6:59 am #

      I would highly recommend that you use Python virtual environments for both Python 2.7 and Python 3.

  11. GokulaKrishnan E December 11, 2018 at 12:34 am #

    Hi Adrian ,
    In Jupyter whenever I am running imshow command display window getting freezes. any suggestion or solution?

    • Adrian Rosebrock December 11, 2018 at 12:37 pm #

      You cannot use cv2.imshow with Jupyter. Use “plt.imshow” from matplotlib instead.

  12. André Soares March 7, 2019 at 8:12 am #

    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?

    • Adrian Rosebrock March 7, 2019 at 4:16 pm #

      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.

    • Apurv March 14, 2019 at 3:42 am #

      Could you resolve this issue? I am also facing the same issue.

  13. naveen g May 18, 2019 at 3:21 am #

    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

Before you leave a comment...

Hey, Adrian here, author of the PyImageSearch blog. I'd love to hear from you, but before you submit a comment, please follow these guidelines:

  1. If you have a question, read the comments first. You should also search this page (i.e., ctrl + f) for keywords related to your question. It's likely that I have already addressed your question in the comments.
  2. If you are copying and pasting code/terminal output, please don't. Reviewing another programmers’ code is a very time consuming and tedious task, and due to the volume of emails and contact requests I receive, I simply cannot do it.
  3. Be respectful of the space. I put a lot of my own personal time into creating these free weekly tutorials. On average, each tutorial takes me 15-20 hours to put together. I love offering these guides to you and I take pride in the content I create. Therefore, I will not approve comments that include large code blocks/terminal output as it destroys the formatting of the page. Kindly be respectful of this space.
  4. Be patient. I receive 200+ comments and emails per day. Due to spam, and my desire to personally answer as many questions as I can, I hand moderate all new comments (typically once per week). I try to answer as many questions as I can, but I'm only one person. Please don't be offended if I cannot get to your question
  5. Do you need priority support? Consider purchasing one of my books and courses. I place customer questions and emails in a separate, special priority queue and answer them first. If you are a customer of mine you will receive a guaranteed response from me. If there's any time left over, I focus on the community at large and attempt to answer as many of those questions as I possibly can.

Thank you for keeping these guidelines in mind before submitting your comment.

Leave a Reply