I'm a Software Engineer & Manager at SoundHound. This is where I share my thoughts on technology, design, travels, and life.

OpenCV on Mac OSX: A step-by-step guide

I’m using OpenCV for my 4th year design project and setting it up was a huge pain. I had to look through a whole bunch of different sites to figure out what to do. There are various ways to install it – through package managers such as Homebrew or Macports, or through the tarball + cmake. Now that I’ve got it set up, I decided to write this little post to explain to others how to go about setting it up.

Note: This method does not set up the Python bindings for OpenCV (still working on that). It only sets up the C++ framework. Also, I tested this on OSX Lion, but it should apply to Snow Leopard or Leopard. Also you will need XCode installed for any of this to work (but you knew that, right?)

On that note, let’s get started.

Download a Package Manager

It’s between Macports, Fink or Homebrew. I used Macports, so I’d recommend that. Download the .dmg file, then install it. You can check to see if it installed successfully by opening your terminal and typing port.

Download the OpenCV Tarball

You can get that from here. Look for the Linux or Mac version. Unzip it after you download it into a folder.

Get cmake

In your terminal, type in the following:sudo port install cmake
This will go fetch cmake and its dependencies and install them onto your system. You can check to see that cmake is installed by typing cmake in a new terminal window.

Build OpenCV

We are going to build OpenCV using cmake. In terminal, navigate to the folder where OpenCV was extracted to. Type in the following:

Make A Sample OpenCV Project

So we now have OpenCV built but we still have to link to the framework in our project.

Start a new XCode Command Line Tool project.

We have to link the .dylib files provided by OpenCV into our project. To do this, right click on the project, and click “Add files to..”

When Finder pops up, hit “/” to bring up the navigation panel.

Type in /usr/local/lib

Add in all the .dylib files that you need. To prevent linker errors, I recommend you initially add ALL the files ending in “…2.3.1.dylib”. There should be a dozen or so. If you know what you need, you can obviously pick and choose.

Now, you should have a bunch of .dylib files in your project. Feel free to move them to a separate group within your project.

Click on the project file and go to “Build Settings”.

Search for “Header Search Paths”

Change the path to /usr/local/include. This is where the header files for OpenCV were built.

Open main.cpp

Copy the following code snippet. This snippet should load a .jpg image and save it as a .png image.

Please read before commenting: Hey guys – thanks a lot for all the comments on this thread. Unfortunately, it’s been a long time since I looked into OpenCV so I don’t remember the details anymore. If you have questions, skim through the comments because many people have posted their solutions. Feel free to comment if you don’t find an answer. On the other hand, if you made some small change that made this work – please add it to the comments so others can find it useful. Thanks!

OpenCV is successfully installed to /usr. And I’m able to compile your cpp file using the terminal with the following command.
g++ -I/usr/include -L/usr/lib -lopencv_core.2.3.1 -lopencv_calib3d.2.3.1 -lopencv_imgproc.2.3.1 -lopencv_legacy.2.3.1 -lopencv_highgui.2.3.1 main.cpp

But I can’t build/run the same cpp file with XCode. I think it’s something wrong with linking. I have set XCode’s Header Search Path to /usr/include and included dylib files from /usr/lib. But still getting the same error.

I got it working. Apparently I have made a mistake by installing OpenCV at /usr. When I set Header Search Path to /usr/include XCode picks some unnecessary headers and fails to link my project it seems. I followed your tutorial from the beginning and the it worked. 🙂

Thanks for the help.

One addition, third include in your code is redundant i guess.
#include
I’m able to successfully run the code without this include.

when i type this: cmake -G “Unix Makefiles” ..
i get this: CMake Error: The source directory “/Users/karansamel” does not appear to contain CMakeLists.txt.
Specify –help for usage, or press the help button on the CMake GUI.
are we supposed to have CMakeLists.txt in there before?

When I tried to type “cmake -G “Unix Makefiles” ..”
I got this massage error
The source directory “/Users/seereennoorwali/Desktop/OpenCV-2.4.0/build” does not appear to contain CMakeLists.txt.
Specify –help for usage, or press the help button on the CMake GUI.

I have some errs when I try the last 2 commands: make -j8 and
sudo make install
it says:
make[2]: *** [modules/highgui/CMakeFiles/opencv_highgui.dir/src/window_cocoa.o] Error 1
make[1]: *** [modules/highgui/CMakeFiles/opencv_highgui.dir/all] Error 2
make: *** [all] Error 2

I don’t know what’s going on. I’m using Lion with Xcode 4.3. Could you please tell me how can I make it right?

I’m sorry Natalie, not sure about that error. It looks like a build error, so my only guess would be that the download was corrupt in some way. Not sure what “error 1” and “error 2” are referring to. Any luck Googling? Try re-tracing your steps from the beginning again or downloading OpenCV again.

I’m getting the same error as Natalie. I’ve tried to re-do everything from the beginning with no luck.

After the command “make -j8” the terminal runs through all the building, and at about 34% of the way through, I get this message: “Undefined symbols for architecture x86_64: …” with a long list of symbols followed by the following: “ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make[2]: *** [lib/libopencv_highgui.2.4.2.dylib] Error 1
make[1]: *** [modules/highgui/CMakeFiles/opencv_highgui.dir/all] Error 2
make: *** [all] Error 2”

I recently ran into this problem too, and beat my head against a brick wall for a few hours.
This was on a Snow Leopard install, where I had previously installed “fink” and many packages under it. I suspected that the cmake was referencing some of the 32 bit stuff I had installed, so I moved the fink sw directory out of the way (from /sw to /sw_tmp), and then completely cleaned out the mac ports and opencv stuff, started over (sudo port uninstall all). I reran the instructions starting from step 1. Success.

Thanks a lot, it did work perfectly well. I tried to do the same on a Cocoa app but I get all sorts of errors. I managed to create a .cpp file on the project with your code and compile it normally, but trying to include this cpp on my AppDelegate causes errors. Even renaming the AppDelegate.m to .mm to ensure it’s C++ causes it to fail. Any idea how to include this on a .m or .mm file?

Having some issues at the end. I’m trying to compile and I keep getting linker errors. It happens to whichever dylib is set first in the “link from library” phase. If I move it around, it gets stuck on that one. Is there something I’m missing? Tried a few times with new projects, following the steps again.

I’m 1 week stuck 🙁
I followed all your steps, but
“ld: warning: ignoring file /Users/radwayahya/OpenCV-2.4.2/mybuild/lib/libopencv_highgui.2.4.2.dylib, file was built for unsupported file format which is not the architecture being linked (armv7)”

any idea ?! thank you in advance. and a lot of thanks for your easy , pure guide

I dont remember to be honest, but don’t worry too much about the warnings as long as you don’t get an error. Unfortunately, I don’t know what’s causing the architecture error. 🙁 Hopefully, someone here can help you out or give you some inspiration. Did you try reading all the comments?

Firstly A lot of thanks, Tilo 🙂
Secondly .. I didn’t find a luck to get opencv2.4.2 to work with this way.
So I’m sharing the alternate way I followed :-
1- Download opencv2.framework from opencv.org (it’s a prebuilt framework -ready to use directly- ) [http://sourceforge.net/projects/opencvlibrary/files/opencv-ios/2.4.2/opencv2.framework.zip/download ]
2- Add it to xcode project as adding any library. if you don’t know about that, don’t worry 🙂 read the content under the title “Adding the OpenCV Framework” from [ http://aptogo.co.uk/2011/09/opencv-framework-for-ios/ ]
3- Add headers >> Follow the steps under the title “Include the OpenCV headers” from [ http://aptogo.co.uk/2011/09/opencv-framework-for-ios/ ]
4 – Write your test code and Run.

Thanks so much. I’ve been reading Learning OpenCV and wanting to start writing code. I’m a iPhone/Mac OS X GUI programmer so the Terminal and low level stuff is new to me. Like you, I found the task of getting all the pieces in the right place in the right order pretty daunting. I am running Mountain Lion, Xcode 4.4.1, and downloaded Open CV 2.4.2. All is working well. I had a couple of problems that I overcame and am posting them in case others have the same issues.
1.) I had spaces in directory names (noob mistake). Replaced them with underscores.
2.) I made my project a C project, needed to be C++
3.) In Xcode build settings, I had to add /usr/local/lib to library search paths
4.) Took me a minute to figure out where the built app was so I could place my .jpg to be converted. Easiest way to get there is right click on the file under the “Products” folder in Xcode and select “Show in Finder” put your .jpg here and obviously the .png that is created will show up here.

Hope this info might help someone. Thanks again for the tutorial, you save me a lot of time. Now it’s time to play…

I encountered only one error like: Lexical or Preprocessor Issue, ‘cvaux.h’ file not fond.

It is so weird since the other two header files are included correctly. And all the step in your guide were run without any error. When setting the header search paths, should I change the value at “debug” or “release”? And when I try to run the cpp file, should I just click on the button “Run”? This is my first time of using the Xcode, so the questions sound “naive”…..

First I want to thank you about this guide, i am new to mac so i faced a lot of issues but finally i got everything working, i want to post to help anyone facing the same.
I have OS X 10.7.5 and opencv 2.4.2

1. I faced problems with the command –> cmake -G “Unix Makefiles” .. downloads -> components, and click install on “Command Line Tools” and it’ll do everything for you.

2. After adding the libraries i got that error, –> linker command failed with exit code 1 (use -v to see invocation) <–, to solve it i include (/usr/local/lib) in "Library Search Paths" just like including (/usr/local/include) in "Header Search Paths".

I don’t know why some words were removed from step 1 so i will write it again,
1. I faced problems with the command –> cmake -G “Unix Makefiles” .. downloads -> components, and click install on “Command Line Tools” and it’ll do everything for you.

Step 1 handling is open Xcode’s Preferences -> downloads -> components, and click install on “Command Line Tools” and it’ll do everything for you or download it from https://developer.apple.com/downloads/

Hi, I am unable to change “header search path”. I am using Xcode 4 on Snow leopard. I followed all your instructions. But when I go to header search path, all I get are two sub blocks i.e ‘Debug’ and ‘release’. I do not know how to proceed. Please help. Thanks..

After a week of trying to install OpenCV I finally encounter this forum and finally my test compiles without errors!!! However I’m new to using a mac structure so the code is not finding “my_image.jpg”. How do I reference to some place in the storage…. what in pc would be something like “C:\my_image.jpg”?

Very good tutorial! Wish I read this first.
It took a long time to install it from tar.bz2 and often failed. After that i installed OpenCV with Macports. Worked fine, but “dylib” directory is /opt/local/lib and header files were placed in /opt/local/include/opencv and /opt/local/include/opencv2.
Creation and setup of the XCode project worked as described. Thank you for that!

Hi, it is excellent tutorial
I got these error, what I suspect about is the dylib files because when I search by typing in /usr/local/lib
I didn’t found and dylib file so I went manually to opt\local\lib and add every dylib file
these are the errors:

Hey Prerna! Thanks. Unfortunately, it’s been a while so I don’t really remember 🙁 Try looking through these comments. People often leave tips about things they did that made it work for them, so hopefully you’ll find something.

Seems straight forward – you just need to alter the path to something so that the program catches it.

Many thanks for an excellent step by step guide. Also thanks to those who took the trouble to post their solutions to problems.

I thought I would add a comment that this works fine with Mountain Lion 10.8.2 and Xcode 4.5.2. The tip about installing the command line tools from the XCode Preferences->Downloads is a real good one. It’s a single click option.

I had no issues with the build of the OpenCV components. I used the 2.4.3 version.

When it came to building the test application I had a couple of the issues mentioned in the comments. I though I would let people know my solutions.

First the missing header file “cvaux.h”. The solution to this is to make sure that the header search path is listed as “recursive” when you add “/usr/local/include” to the header search path. No need to substitute files or rename things.

The second problem is the linker error. This depends on how you added the libopencv_xxxx files to your project. If when you added the files you let XCode copy the files to the project directory you don’t get this problem. If you un-checked the “add files to project” option then you will get the error. Its a personal preference if you want to add the libraries to the project but if you chose not to you will need to add the path “/usr/local/lib” to the “Library Search Paths”

I saw a number of comments about the app not finding the image file. This needs to go in the same folder as the application, right click on the app under products and show in finder. And the important point is that the image file needs to be called my_image.jpg 🙂 That one took me a couple of goes before I was groaning at my stupidity.

Once again, this is one of the best How To’s I’ve ever used. Thank you

Trying to install this – have installed/downloaded all the required apps and compilers. Receiving following error at first command:

Miless-Macbook-Pro:~ Apple$ sudo port install cmake
Warning: The Command Line Tools for Xcode don’t appear to be installed; most ports will likely fail to build.
Warning: See http://guide.macports.org/chunked/installing.xcode.html for more information.
—> Computing dependencies for cmakeError: Unable to execute port: can’t read “build.cmd”: Failed to locate ‘make’ in path: ‘/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin’ or at its MacPorts configuration time location, did you move it?
Miless-Macbook-Pro:~ Apple$ sudo port install cmake
Warning: The Command Line Tools for Xcode don’t appear to be installed; most ports will likely fail to build.
Warning: See http://guide.macports.org/chunked/installing.xcode.html for more information.
—> Computing dependencies for cmakeError: Unable to execute port: can’t read “build.cmd”: Failed to locate ‘make’ in path: ‘/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin’ or at its MacPorts configuration time location, did you move it?
Miless-Macbook-Pro:~ Apple$

I sent a reply about a week ago, but I am not sure if you received it. I am desperately looking for help in trying to make a build. I get the following error no matter what I try:

Apple$ sudo port install cmake
Password:
Warning: The Command Line Tools for Xcode don’t appear to be installed; most ports will likely fail to build.
Warning: See http://guide.macports.org/chunked/installing.xcode.html for more information.
—> Computing dependencies for cmakeError: Unable to execute port: can’t read “build.cmd”: Failed to locate ‘make’ in path: ‘/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin’ or at its MacPorts configuration time location, did you move it?

Could you possibly kindly let me know how to resolve this ASAP? Much appreciated!

In terminal i’ve installed cmake and build OpenCV. When i’m typing ls /usr/local/lib i’ve got a lot of files .dylib. When I link the .dylib files in my project and text in /usr/local/lib, there are no .dylib. via terminal i see but via “Add Files to ..” i don’t .Tell me plz what’s wrong. Thanks !!!!

I thought I would add a little bit of detail to step 1, which tripped me up a bit.

When you create your xCode project, be sure to set the project “Type” to C++, (using the appropriate dropdown list/selector). Otherwise, the project “Type” is set to C by default. In xCode 4.6, this setting appears on the second screen of project creation.

When I created the default C project, obviously a main.c file was automatically created. And when I went to compile/build, I received the following error:
Lexical or Preprocessor Issue ‘list’ file not found

The issue went away and the compile/build succeeded after I created a new C++ project.

In addition to properly naming your image file “my_image.jpg”, you must put the image in the same directory where your TARGET APPLICATION resides, not the directory where your source code resides. You can find this directory by right clicking on the appropriate target in your project’s Products folder, and then selecting “Show in Finder”.

Put the image there.

Then, do not double click the application in that folder. I tried that and it didn’t work. You must actually “Run” the application from xCode by selecting Product -> Run from the main dropdown menu. After running, you should navigate back to the folder with the target application. You should notice a new file “my_image_copy.png” in there.

hi when i am trying to install the open cv i get following error and while i went to /usr/local/ i couldnt any fine except CUDA which i had installed before why is this problem. i have attached the error message hereclang: error: unsupported option ‘-dumpspecs’
clang: error: no input files
CMake Error at cuda_compile_generated_matrix_operations.cu.o.cmake:206 (message):
Error generating
/opencv-2.4.5/build/modules/core/CMakeFiles/cuda_compile.dir/src/cuda/./cuda_compile_generated_matrix_operations.cu.o

thank you for your post, I followed everything you mentioned but my Xcode tells me that the function cvLoadImage and cvSaveImage are undeclared. I did set the right header search path but I have no idea why Xcode can’t find them.

thank you for the tutorial. While trying to build the program I got this error: “/usr/local/include/opencv/cvaux.hpp:49:10: ‘cvaux.h’ file not found with include; use “quotes” instead”. I tried the solution in this page to change to cvaux.hpp to cvaux.h and it did work. Is this the right way to do it?

Hi Tilo, thanks a lot for the installation tutorial. I’ve done the installation but when I tried to run the given code, I didn’t get the result as I expected. It was said
“failed to load input image
Program ended with exit code: 255”.
I already download some jpg picture and rename it to my_image.jpg as well. Do you have any idea how to fix it? Thanks before for your help and attention.

hi
I have a Macbook 10/.10.2 Yosemite and I’m trying to install OpenCV which I need for my PhD.
I tried your tutorial but unfortunately the link you provided for Tarball (Download the OpenCV Tarball:http://opencv.willowgarage.com/wiki/InstallGuide) doesn’t work!
Would you please help me with this?

Very much enjoyed this post, however, I’m getting an odd error. First off, none of my files in /usr/local/lib end in .dylib, they all end in .a. Secondly, I get this error that overflows my error stack: Apple-Mach 0 Linker (id) error