OpenCV, Python 3, and Homebrew Walkthrough
Post by Gravity Jack research team member, Marc Rollins.
Do you want to use OpenCV, but can't get it to work with Python 3? You've come to the right place! Here at Gravity Jack we tackle computer vision problems using OpenCV as one of the tools in our arsenal. It’s very useful for implementing computer vision algorithms, but getting the library installed properly isn’t always easy. Since our research team all develops on OS X, we also make use of the Homebrew package manager. Usually Homebrew makes dependency management a breeze, but OpenCV is a curious exception to this rule. This seems especially true when trying to use the Python bindings that OpenCV provides. Even though OpenCV includes the Python 2 bindings by default, the same is not true of Python 3. What follows are the instructions to correctly install.
I’ll assume that Homebrew is up-to-date and
brew doctor doesn't bring up anything serious before installing OpenCV. There are two steps to correctly install Python support. First install the
opencv3 package with Homebrew, and then tell Python 3 where to look for the OpenCV binary:
$ brew install opencv3 --with-python3 --c++11 --with-contrib $ brew link --force opencv3
Then fire up Python and import the OpenCV module. Despite OpenCV 3 being installed, the Python package is still named
cv2. Everything should go off without a hitch:
$ python3 Python 3.5.1 (default, May 20 2016, 12:52:19) [GCC 4.2.1 Compatible Apple LLVM 7.3.0 (clang-703.0.31)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import cv2 >>> print(cv2.__version__) 3.1.0 >>> # It worked!
Additional step for virtualenv users
So far I've assumed you're working with the standard Python installation. If you're using a virtual environment, there is one more step to get Python to recognize the OpenCV package. Open a command prompt and
cd to the directory where your virtualenv is installed. Here I assume that the virtual environment exists in the
venv directory. Then run this command:
echo /usr/local/opt/opencv3/lib/python3.5/site-packages >> venv/lib/python3.5/site-packages/opencv3.pth
And you should now be able to
import cv2 from within your virtual environment! If you have a different Python version than
3.5, you will need to change the major version numbers in the command above. (i.e. If you are using Python 3.4.3, replace
python3.5 above with
If something went wrong, check out the Troubleshooting section below.
Let’s break down the commands and options a little bit:
brew install opencv3 — This specifies the package to install. Note that Homebrew has both an
opencv3 package. The
opencv formula will install the latest version of OpenCV 2.
--with-python3 — Tells Homebrew to include Python 3 support for OpenCV.
--c++11 — Tells Homebrew to build with C++11 support. By now you're hopefully using a compiler that supports modern C++!
--with-contrib — This is optional, but recommended. The
contrib module of OpenCV contains some experimental features, including a number of useful feature descriptors like SIFT, SURF, and FREAK.
After opening Python and importing OpenCV, you may run into an
ImportError: No module named 'cv2'. This error can occur for one of three reasons:
- You forgot to install using the
--with-python3option. Don't worry, it happens to the best of us! Simply
brew reinstall opencv3 --with-python3 --c++11 --with-contribto reinstall with Python 3 support. If that doesn't work, go to the next step.
- OpenCV was not linked correctly. Run the command
brew unlink opencv3 && brew link --force opencv3. That should successfully re-link the python libraries.
- You're inside a virtualenv. If you're using a virtual environment, you may have forgotten the final installation step. Follow the instruction above.
Undefined symbols error
During installation with
brew, you may come across an undefined symbols error that looks like this:
Undefined symbols for architecture x86_64: "Imf_2_2::Chromaticities::Chromaticities(Imath_2_1::Vec2<float> const&, Imath_2_1::Vec2<float> const&, Imath_2_1::Vec2<float> const&, Imath_2_1::Vec2<float> const&)", referenced from: cv::ExrDecoder::ExrDecoder() in grfmt_exr.cpp.o "Imf_2_2::Header::Header(int, int, float, Imath_2_1::Vec2<float> const&, float, Imf_2_2::LineOrder, Imf_2_2::Compression)", referenced from: cv::ExrEncoder::write(cv::Mat const&, std::__1::vector<int, std::__1::allocator<int> > const&) in grfmt_exr.cpp.o ld: symbol(s) not found for architecture x86_64 clang: error: linker command failed with exit code 1 (use -v to see invocation) make: *** [lib/libopencv_imgcodecs.3.1.0.dylib] Error 1 make: *** [modules/imgcodecs/CMakeFiles/opencv_imgcodecs.dir/all] Error 2 make: *** [all] Error 2
If you happen to see this, the workaround is simple: add the
--without-openexr option to your installation command:
install opencv3 --without-openexr --with-python3 --c++11 --with-contrib
This error has something to do with the
Imf_2_2 class, which is part of OpenEXR. Unless you specifically need OpenEXR, you can safely install OpenCV without it.