OpenCV Installation Guide
(Or if you want the latest code being developed each day, get it from our Git server)
2) Install CMake and some prerequisite libraries.
- (You can skip this if you just use the pre-built Visual Studio 2008/2010 binaries for Windows).
3) Use CMake to build OpenCV binaries (such as "opencv_core243.dll" or "libopencv_core.so.2.4.3") from the source code.
- (You can skip this if you use the pre-built Visual Studio 2008/2010 binaries for Windows).
4) Finally you must configure your C/C++ compiler so it knows where to find OpenCV for your projects.
- (Installation guides for popular compilers are given below).
1) Get the current stable OpenCV version (updated yearly)
Windows: run the Windows EXE and tell it where to install OpenCV. Note that prebuilt v2.3.0 or older packages were only 32-bit and didn't include TBB support (thus you couldn't use multiple cores unless you multithreaded your own application). So it is recommended to rebuild old versions from source code using CMake with the same compiler that you use to build your applications.
Linux/MacOSX/other operating systems: download the source tarball (OpenCV-x.y.z.tar.bz2) for building with CMake.
Or get the cutting-edge OpenCV from the Git repository (updated daily)
- In Linux/MacOSX it can be done using the command line, e.g.:
cd ~/<my_working_directory> git clone git://code.opencv.org/opencv.git
2) Install Prerequisite Libraries and Tools
C/C++ compiler (OpenCV 2.3 is known to work with latest versions of Visual Studio (such as VS2008, VS2010, including Express Editions) and MinGW on Windows, Xcode 3.2 or later on MacOSX, GCC 4.3 or later on Linux and other Unix-like systems). In the case of older compilers you may prefer OpenCV 1.1 instead.
CMake 2.6 or later. CMake is now the only method of building OpenCV daily snapshots.
(Optional) Git client (e.g. command-line git tool, or others on the new developer's website.
(Optional) Python 2.6.x or 2.7.x (Python 3.x support status is unknown) and Numpy, including the development files: Python.h, ndarrayobject.h etc. in order to build Python wrappers. (Make sure you install Numpy into the same installed version of Python that the OpenCV build uses i.e. run Numpy's setup.py with that Python binary. By default the OpenCV build system will choose the most recent version of Python that it can find, or you can force it to use a specific version using the PYTHON_EXECUTABLE variable when you invoke cmake.)
(Optional) Intel TBB to enable parallel code in OpenCV. We do not use OpenMP any longer. Important note: Only TBB 2.2 or later will work. For Ubuntu 9.10 users - you can take libtbb2 and libtbb-dev packages from Ubuntu 10.04 (Lucid Lynx), they are known to install and work flawlessly on 9.10.
eg: Run this on Ubuntu: sudo apt-get install libtbb2 libtbb-dev
- Then you can pass WITH_TBB=ON to CMake when configuring OpenCV.
(Optional) Qt 4.6 or later. You can use Qt as HighGUI backend on any platforms (Windows, Linux, Mac) by passing WITH_QT=ON to CMake when configuring OpenCV. See Qt-OpenCV-Multithreaded for required steps.
(Optional) IPP 5.1 to 6.1 (OpenCV 2.3 should also work fine with IPP 7). OpenCV does not require IPP, but can be configured to use IPP to make color conversion, Haar training and DFT functions run faster.
(Optional) LiveTeX distribution (or MiKTeX on Windows, MacTeX on Mac) and Sphinx (http://sphinx.pocoo.org) to build the up-to-date OpenCV documentation in PDF or HTML formats.
(Optional) The latest CUDA Toolkit to build with GPU support (only available for NVidia GPUs).
Extra Prerequisites (Linux/BSD/other Unix-like OSes)
- pkg-config. It is used at the configuration stage and also simplifies the further use of OpenCV itself.
(Optional) gtk+ 2.x (libgtk2.0-dev) and perhaps the related packages (glib, gthread etc.).
- This is the default GUI backend for highgui on OSes other than Windows and MacOSX.
(Optional) libjpeg, libtiff, libjasper, libpng and zlib, openexr. Install any of those with the associated
- development packages (libjpeg-dev etc. on Debian/Ubuntu) if you want to use those stock libraries to read and write images in the respective formats, instead of using the versions supplied with OpenCV (openexr is not supplied)
(Optional) ffmpeg, libgstreamer, libv4l, libxine, unicap, libdc1394 2.x.
You should have some/all of these packages installed (together with associated development packages) to add video capturing, video decoding and video encoding capabilities to highgui. The output of the cmake will show you, which of the packages have been detected and will be used in highgui. (Enable full video support with FFMPEG). For example, on Ubuntu 9.10 all the necessary ffmpeg files can be installed using the following command:
sudo apt-get install libavformat-dev libswscale-dev
Extra Prerequisites (MacOSX)
Xcode 3.2 or later. It does not only include the required C++ compiler, but also Cocoa, QTKit and other frameworks that make highgui on MacOSX functional. Besides, CMake can generate Xcode projects by the command "cmake -G Xcode", so you can build OpenCV conveniently from within the IDE. Additional information can be found on the Mac_OS_X_OpenCV_Port page.
Extra Prerequisites (Android)
See the Android build page for details.
3) Build the OpenCV library from source using CMake and your C++ Compiler
Note: Specific guides to compiling the OpenCV source are also available for Mac, Ubuntu (prebuilt packages), Debian & Ubuntu (manual install), Linux and MinGW. Visual Studio users may skip this section since their installation comes with prebuilt DLL and LIB files, unless if they want to customize OpenCV such as with IPP or CUDA or Qt. iPhone/iOS is not officially supported by OpenCV but there are ways to use it, currently recommended is Building OpenCV for iPhone in One Click.
Configure using CMake
- In general you should:
Create a temporary directory, which we denote as <cmake_binary_dir>, where you want to put the generated Makefiles, Visual Studio, Xcode or Eclipse etc. project files as well the object files and output binaries. You can do it using CMake GUI.
If you use CMake GUI, execute "Configure" to do the initial configuration, then adjust any options, then press "Configure" again and then press "Generate". If you have them installed, turn on TBB and IPP support in order to get a better performance. Also, if you want to build Python wrappers, samples or the reference manual in PDF, you should explicitly turn them on. (It might be wise to try first with all options turned off, and make sure that works first.)
If you are using command line, enter the <cmake_binary_dir> and type
cmake [<some optional parameters...>] <path to the OpenCV source directory>
- You may want instead to use cmake's GUI as follows:
cmake-gui [<some optional parameters...>] <path to the OpenCV source directory>
- For example, if you downloaded the project to ~/projects/opencv, you can do the following:
cd ~/projects/opencv # the directory containing INSTALL, CMakeLists.txt etc. mkdir release cd release cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local -D BUILD_PYTHON_SUPPORT=ON ..
- That will generate makefiles for the Release configuration and will put them in ~/projects/opencv/release directory.
- . ~ Note for newbie linux users:
- Do the cmake step from inside the folder where you want to build OpenCV. It is a good practice to keep your source and build files (the files that are going to be generated after the cmake step) separately. Remember to specify the source folder while invoking cmake as the last argument. Otherwise cmake will scan for CMakeLists.txt file in the usual standard location /usr/local/src and will throw an error. Unzipping all OpenCV directories from the source files to the src folder is not an elegant way of doing things in linux.
. If you have a gui version of cmake installed, just do this from inside the build folder, $ ccmake <OpenCV source folder>
- Another example for Windows users (assuming the .exe extracted files to C:\OpenCV2.4\)
cd C:\OpenCV2.4 # the directory containing INSTALL, CMakeLists.txt etc. mkdir release cd release cmake -D:CMAKE_BUILD_TYPE=RELEASE C:\OpenCV2.4
Note that the use of the colon after the -D is required on Windows Vista (include if cmake is giving errors on other Windows distro's as well). If you are using MS Visual Studio cmake exits with an error message "error PRJ0003: Error spawning 'cmd.exe', make sure that you have the correct VC++ Executable Directories set (see here).
Using TBB (Optional). If you have TBB installed (see the Prerequisites), turn on WITH_TBB option, adjust the TBB include and library paths if needed. You should see the following message in the CMake output:
USE TBB: YES
Using IPP (Optional). If you have IPP installed on your machine and want to build OpenCV with IPP support, check if IPP is turned on in CMake configuration options and if it was detected. First, look at the CMake output. If it prints
USE IPP: NO
It means that IPP was not turned on or it was not detected. In this case turn it on (USE_IPP=ON) and pass the correct path to IPP shared libraries (IPP_PATH=<...>), like in the example below. While OpenCV currently uses static IPP libraries, it derives their path from the supplied path to the shared/dynamic IPP libraries.
cmake -D:CMAKE_BUILD_TYPE=RELEASE -D:USE_IPP=ON -D:IPP_PATH="C:\Program Files\Intel\IPP\6.1.031\ia32\bin" C:\OpenCV2.4
- (It's also easy to do the same using CMake GUI)
- If you did everything right, you will see the following in the CMake output:
USE IPP: <ipp_path>
- If there are multiple IPP versions installed on the machine (not necessarily all of them are in the system path) and you want to use the particular one, different from what CMake has found, just specify the correct IPP_PATH.
Using CUDA (Optional). If you have the latest CUDA Toolkit installed (see the Prerequisites), turn on WITH_CUDA option, and verify that all paths and libraries were detected correctly. You should see the following message in the CMake output:
USE CUDA: YES
More information about GPU support in OpenCV can be found here: OpenCV_GPU
Compile using GCC from command line
- Generate makefiles using CMake (choose "MinGW Makefiles" generator on Windows, "Unix Makefiles" on other OSes) as described above.
Enter the output CMake directory (denoted as <cmake_binary_dir> further) and type "mingw32-make" on Windows, "make -j [optional_number_of_threads]" on Unix. Windows users can also run parallel build of OpenCV. To do that, please, define "SHELL" environment variable (My Computer--[Right button click]-->Properties->Advanced->Environment Variables->Path) and set it to "cmd.exe" (without quotes). Then you can run "mingw32-make -j" (note that "-j" must go without any numerical parameter).
- [Linux, MacOSX] Then you can optionally run "sudo make install" (on Linux or MacOSX). Note, that if you are using CMake (and, therefore, OpenCVConfig.cmake) for your projects, it is not necessary to run "make install". Just use OpenCV from where you built it. And actually this is recommended approach, since it does not pollute system directories with potentially conflicting OpenCV versions.
[Windows] If you built OpenCV as dynamic libraries (DLLs), you may want to add <cmake_binary_dir>\bin to the system path (My Computer--[Right button click]-->Properties->Advanced->Environment Variables->Path) to let Windows find "opencv_core240.dll" etc.)
Compile using Visual Studio
- generate solutions using CMake, as described above. Make sure, you chose the proper generator (32-bit or 64-bit)
- launch Visual Studio, locate and open the "OpenCV.sln" solution file in your generated build folder (eg: "C:\OpenCV\build\OpenCV.sln"). Select "Debug" configuration, build the solution (Ctrl-Shift-B), and/or select "Release" and build it.
add <cmake_binary_dir>\bin\Release, <cmake_binary_dir>\bin\Debug (containing "opencv_core*.dll" and "opencv_core*d.dll", respectively) to the system path (My Computer--[Right button click]-->Properties->Advanced->Environment Variables->Path)
Compile using Xcode
- generate Xcode project using CMake, as described above.
- launch Xcode, locate and open OpenCV.xcodeproj. Select "Debug", build the BUILD_ALL target (Cmd-B), select "Release" and build it too.
Building the HTML Documentation
- Go to the opencv build directory (where cmake will put the library and built sample files etc).
Type make html_docs
- You may turn on "BUILD_EXAMPLES" in CMake GUI or run cmake with "-D BUILD_EXAMPLES=ON" option, then it will include short demo samples to the build. Note that some of them need image files from the original source directory, you may just copy them to the bin directory.
You can also run correctness tests <cmake_binary_dir>/bin[/debug|/release]/cxcoretest and cvtest.
Testing Python wrappers
- As long as you build Python wrappers and installed them, you can just enter opencv/samples/python and run the samples, e.g.
- If you want to try Python samples without installing OpenCV, put cv.so and cv2.so (called cv.pyd and cv2.pyd on Windows) to opencv/samples/python directory, or rather add the directory containing cv.so/cv.pyd to PYTHONPATH, e.g.
4) Configure your own projects to use OpenCV
- Installation guides are available for:
- Or you can add opencv 'include', 'lib' and 'bin' subdirectories to your IDE settings.
- Or for hand-written Makefiles you can specify the necessary paths and options manually, e.g.:
g++ -o my_example my_example.cpp -lopencv_core -lopencv_imgproc -lopencv_calib3d -lopencv_video -lopencv_features2d -lopencv_ml -lopencv_highgui -lopencv_objdetect -lopencv_contrib -lopencv_legacy
- Note that if you build OpenCV statically, you also need to link all the OpenCV dependencies
- Or you can use pkg-config and the provided "opencv.pc".
- Make sure that opencv.pc is found by pkg-config:
pkg-config opencv --libs # should print something like -lopencv_core -lopencv_imgproc ...
- You can now use it in your Makefiles or build scripts, e.g.:
g++ -o my_example my_example.cpp `pkg-config opencv --cflags --libs`
- Make sure that opencv.pc is found by pkg-config:
5) Use OpenCV for state-of-the-art projects!
If you are new to OpenCV, you should first read the Beginners FAQ.
There are also some info on topics (such as Blob Detection and Face Recognition) in the FAQ Guide.
There are some tutorials (such as POSIT 3D Pose Estimation) in Tutorials.
- There are many sample programs that come with OpenCV in the "samples\c\" folder.
The best way to learn how to use OpenCV is to read the O'Reilly book "Learning OpenCV: Computer Vision with the OpenCV Library", that explains many important concepts such as Image Processing, Histogram Matching, Object Tracking, 3D Pose Estimation, Stereo Camera Calibration, Machine Learning, etc.
An up-to-date version of this manual can be found here: http://opencv.willowgarage.com/wiki/InstallGuide