Home | History | Annotate | Download | only in windows_install
      1 Installation in Windows {#tutorial_windows_install}
      2 =======================
      3 
      4 The description here was tested on Windows 7 SP1. Nevertheless, it should also work on any other
      5 relatively modern version of Windows OS. If you encounter errors after following the steps described
      6 below, feel free to contact us via our [OpenCV Q&A forum](http://answers.opencv.org). We'll do our
      7 best to help you out.
      8 
      9 @note To use the OpenCV library you have two options: @ref tutorial_windows_install_prebuilt or
     10 @ref tutorial_windows_install_build. While the first one is easier to complete, it only works if you are coding
     11 with the latest Microsoft Visual Studio IDE and doesn't take advantage of the most advanced
     12 technologies we integrate into our library. .. _Windows_Install_Prebuild:
     13 
     14 Installation by Using the Pre-built Libraries {#tutorial_windows_install_prebuilt}
     15 =============================================
     16 
     17 -#  Launch a web browser of choice and go to our [page on
     18     Sourceforge](http://sourceforge.net/projects/opencvlibrary/files/opencv-win/).
     19 -#  Choose a build you want to use and download it.
     20 -#  Make sure you have admin rights. Unpack the self-extracting archive.
     21 -#  You can check the installation at the chosen path as you can see below.
     22 
     23     ![](images/OpenCV_Install_Directory.png)
     24 
     25 -#  To finalize the installation go to the @ref tutorial_windows_install_path section.
     26 
     27 Installation by Making Your Own Libraries from the Source Files {#tutorial_windows_install_build}
     28 ===============================================================
     29 
     30 You may find the content of this tutorial also inside the following videos:
     31 [Part 1](https://www.youtube.com/watch?v=NnovZ1cTlMs) and [Part 2](https://www.youtube.com/watch?v=qGNWMcfWwPU), hosted on YouTube.
     32 
     33 \htmlonly
     34 <div align="center">
     35 <iframe title="Install OpenCV by using its source files - Part 1" width="560" height="349" src="http://www.youtube.com/embed/NnovZ1cTlMs?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
     36 <iframe title="Install OpenCV by using its source files - Part 2" width="560" height="349" src="http://www.youtube.com/embed/qGNWMcfWwPU?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
     37 </div>
     38 \endhtmlonly
     39 
     40 **warning**
     41 
     42 These videos above are long-obsolete and contain inaccurate information. Be careful, since
     43 solutions described in those videos are no longer supported and may even break your install.
     44 
     45 If you are building your own libraries you can take the source files from our [Git
     46 repository](https://github.com/Itseez/opencv.git).
     47 
     48 Building the OpenCV library from scratch requires a couple of tools installed beforehand:
     49 
     50 -   An IDE of choice (preferably), or just a CC++ compiler that will actually make the binary files.
     51     Here we will use the [Microsoft Visual Studio](https://www.microsoft.com/visualstudio/en-us).
     52     However, you can use any other IDE that has a valid CC++ compiler.
     53 -   [CMake](http://www.cmake.org/cmake/resources/software.html), which is a neat tool to make the project files (for your chosen IDE) from the OpenCV
     54     source files. It will also allow an easy configuration of the OpenCV build files, in order to
     55     make binary files that fits exactly to your needs.
     56 -   Git to acquire the OpenCV source files. A good tool for this is [TortoiseGit](http://code.google.com/p/tortoisegit/wiki/Download). Alternatively,
     57     you can just download an archived version of the source files from our [page on
     58     Sourceforge](http://sourceforge.net/projects/opencvlibrary/files/opencv-win/)
     59 
     60 OpenCV may come in multiple flavors. There is a "core" section that will work on its own.
     61 Nevertheless, there is a couple of tools, libraries made by 3rd parties that offer services of which
     62 the OpenCV may take advantage. These will improve its capabilities in many ways. In order to use any
     63 of them, you need to download and install them on your system.
     64 
     65 -   The [Python libraries](http://www.python.org/downloads/) are required to build the *Python interface* of OpenCV. For now use the
     66     version `2.7.{x}`. This is also a must if you want to build the *OpenCV documentation*.
     67 -   [Numpy](http://numpy.scipy.org/) is a scientific computing package for Python. Required for the *Python interface*.
     68 -   [Intel Threading Building Blocks (*TBB*)](http://threadingbuildingblocks.org/file.php?fid=77) is used inside OpenCV for parallel code
     69     snippets. Using this will make sure that the OpenCV library will take advantage of all the cores
     70     you have in your systems CPU.
     71 -   [Intel Integrated Performance Primitives (*IPP*)](http://software.intel.com/en-us/articles/intel-ipp/) may be used to improve the performance
     72     of color conversion, Haar training and DFT functions of the OpenCV library. Watch out, since
     73     this isn't a free service.
     74 -   [Intel IPP Asynchronous C/C++](http://software.intel.com/en-us/intel-ipp-preview) is currently focused delivering Intel Graphics
     75     support for advanced image processing and computer vision functions.
     76 -   OpenCV offers a somewhat fancier and more useful graphical user interface, than the default one
     77     by using the [Qt framework](http://qt.nokia.com/downloads). For a quick overview of what this has to offer look into the
     78     documentations *highgui* module, under the *Qt New Functions* section. Version 4.6 or later of
     79     the framework is required.
     80 -   [Eigen](http://eigen.tuxfamily.org/index.php?title=Main_Page#Download) is a C++ template library for linear algebra.
     81 -   The latest [CUDA Toolkit](http://developer.nvidia.com/cuda-downloads) will allow you to use the power lying inside your GPU. This will
     82     drastically improve performance for some algorithms (e.g the HOG descriptor). Getting more and
     83     more of our algorithms to work on the GPUs is a constant effort of the OpenCV team.
     84 -   [OpenEXR](http://www.openexr.com/downloads.html) source files are required for the library to work with this high dynamic range (HDR)
     85     image file format.
     86 -   The [OpenNI Framework](http://www.openni.org/) contains a set of open source APIs that provide support for natural
     87     interaction with devices via methods such as voice command recognition, hand gestures and body
     88     motion tracking.
     89 -   [Miktex]( http://miktex.org/2.9/setup) is the best [TEX](https://secure.wikimedia.org/wikipedia/en/wiki/TeX) implementation on
     90     the Windows OS. It is required to build the *OpenCV documentation*.
     91 -   [Sphinx](http://sphinx.pocoo.org/) is a python documentation generator and is the tool that will actually create the
     92     *OpenCV documentation*. This on its own requires a couple of tools installed, We will cover this
     93     in depth at the @ref tutorial_windows_install_sphinx "How to Install Sphinx" section.
     94 
     95 Now we will describe the steps to follow for a full build (using all the above frameworks, tools and
     96 libraries). If you do not need the support for some of these you can just freely skip this section.
     97 
     98 ### Building the library
     99 
    100 -#  Make sure you have a working IDE with a valid compiler. In case of the Microsoft Visual Studio
    101     just install it and make sure it starts up.
    102 -#  Install [CMake](http://www.cmake.org/cmake/resources/software.html). Simply follow the wizard, no need to add it to the path. The default install
    103     options are OK.
    104 -#  Download and install an up-to-date version of msysgit from its [official
    105     site](http://code.google.com/p/msysgit/downloads/list). There is also the portable version,
    106     which you need only to unpack to get access to the console version of Git. Supposing that for
    107     some of us it could be quite enough.
    108 -#  Install [TortoiseGit](http://code.google.com/p/tortoisegit/wiki/Download). Choose the 32 or 64 bit version according to the type of OS you work in.
    109     While installing, locate your msysgit (if it doesn't do that automatically). Follow the
    110     wizard -- the default options are OK for the most part.
    111 -#  Choose a directory in your file system, where you will download the OpenCV libraries to. I
    112     recommend creating a new one that has short path and no special charachters in it, for example
    113     `D:/OpenCV`. For this tutorial I'll suggest you do so. If you use your own path and know, what
    114     you're doing -- it's OK.
    115     -#  Clone the repository to the selected directory. After clicking *Clone* button, a window will
    116         appear where you can select from what repository you want to download source files
    117         (<https://github.com/Itseez/opencv.git>) and to what directory (`D:/OpenCV`).
    118     -#  Push the OK button and be patient as the repository is quite a heavy download. It will take
    119         some time depending on your Internet connection.
    120 
    121 -#  In this section I will cover installing the 3rd party libraries.
    122     -#  Download the [Python libraries](http://www.python.org/downloads/) and install it with the default options. You will need a
    123         couple other python extensions. Luckily installing all these may be automated by a nice tool
    124         called [Setuptools](http://pypi.python.org/pypi/setuptools#downloads). Download and install
    125         again.
    126         @anchor tutorial_windows_install_sphinx
    127     -#  Installing Sphinx is easy once you have installed *Setuptools*. This contains a little
    128         application that will automatically connect to the python databases and download the latest
    129         version of many python scripts. Start up a command window (enter *cmd* into the windows
    130         start menu and press enter) and use the *CD* command to navigate to your Python folders
    131         Script sub-folder. Here just pass to the *easy_install.exe* as argument the name of the
    132         program you want to install. Add the *sphinx* argument.
    133 
    134         ![](images/cmsdstartwindows.jpg)
    135 
    136         ![](images/Sphinx_Install.png)
    137 
    138         @note
    139         The *CD* navigation command works only inside a drive. For example if you are somewhere in the
    140         *C:* drive you cannot use it this to go to another drive (like for example *D:*). To do so you
    141         first need to change drives letters. For this simply enter the command *D:*. Then you can use
    142         the *CD* to navigate to specific folder inside the drive. Bonus tip: you can clear the screen by
    143         using the *CLS* command.
    144 
    145         This will also install its prerequisites [Jinja2](http://jinja.pocoo.org/docs/) and
    146         [Pygments](http://pygments.org/).
    147 
    148     -#  The easiest way to install Numpy is to just download its binaries from the [sourceforge page](http://sourceforge.net/projects/numpy/files/NumPy/).
    149         Make sure your download and install
    150         exactly the binary for your python version (so for version `2.7`).
    151     -#  Download the [Miktex](http://miktex.org/2.9/setup) and install it. Again just follow the wizard. At the fourth step make
    152         sure you select for the *"Install missing packages on-the-fly"* the *Yes* option, as you can
    153         see on the image below. Again this will take quite some time so be patient.
    154 
    155         ![](images/MiktexInstall.png)
    156 
    157     -#  For the [Intel Threading Building Blocks (*TBB*)](http://threadingbuildingblocks.org/file.php?fid=77)
    158         download the source files and extract
    159         it inside a directory on your system. For example let there be `D:/OpenCV/dep`. For installing
    160         the [Intel Integrated Performance Primitives (*IPP*)](http://software.intel.com/en-us/articles/intel-ipp/)
    161         the story is the same. For
    162         exctracting the archives I recommend using the [7-Zip](http://www.7-zip.org/) application.
    163 
    164         ![](images/IntelTBB.png)
    165 
    166     -#  For the [Intel IPP Asynchronous C/C++](http://software.intel.com/en-us/intel-ipp-preview) download the source files and set environment
    167         variable **IPP_ASYNC_ROOT**. It should point to
    168         `<your Program Files(x86) directory>/Intel/IPP Preview */ipp directory`. Here \* denotes the
    169         particular preview name.
    170     -#  In case of the [Eigen](http://eigen.tuxfamily.org/index.php?title=Main_Page#Download) library it is again a case of download and extract to the
    171         `D:/OpenCV/dep` directory.
    172     -#  Same as above with [OpenEXR](http://www.openexr.com/downloads.html).
    173     -#  For the [OpenNI Framework](http://www.openni.org/) you need to install both the [development
    174         build](http://www.openni.org/downloadfiles/opennimodules/openni-binaries/21-stable) and the
    175         [PrimeSensor
    176         Module](http://www.openni.org/downloadfiles/opennimodules/openni-compliant-hardware-binaries/32-stable).
    177     -#  For the CUDA you need again two modules: the latest [CUDA Toolkit](http://developer.nvidia.com/cuda-downloads) and the *CUDA Tools SDK*.
    178         Download and install both of them with a *complete* option by using the 32 or 64 bit setups
    179         according to your OS.
    180     -#  In case of the Qt framework you need to build yourself the binary files (unless you use the
    181         Microsoft Visual Studio 2008 with 32 bit compiler). To do this go to the [Qt
    182         Downloads](http://qt.nokia.com/downloads) page. Download the source files (not the
    183         installers!!!):
    184 
    185         ![](images/qtDownloadThisPackage.png)
    186 
    187         Extract it into a nice and short named directory like `D:/OpenCV/dep/qt/` . Then you need to
    188         build it. Start up a *Visual* *Studio* *Command* *Prompt* (*2010*) by using the start menu
    189         search (or navigate through the start menu
    190         All Programs --\> Microsoft Visual Studio 2010 --\> Visual Studio Tools --\> Visual Studio Command Prompt (2010)).
    191 
    192         ![](images/visualstudiocommandprompt.jpg)
    193 
    194         Now navigate to the extracted folder and enter inside it by using this console window. You
    195         should have a folder containing files like *Install*, *Make* and so on. Use the *dir* command
    196         to list files inside your current directory. Once arrived at this directory enter the
    197         following command:
    198         @code{.bash}
    199         configure.exe -release -no-webkit -no-phonon -no-phonon-backend -no-script -no-scripttools
    200                       -no-qt3support -no-multimedia -no-ltcg
    201         @endcode
    202         Completing this will take around 10-20 minutes. Then enter the next command that will take a
    203         lot longer (can easily take even more than a full hour):
    204         @code{.bash}
    205         nmake
    206         @endcode
    207         After this set the Qt enviroment variables using the following command on Windows 7:
    208         @code{.bash}
    209         setx -m QTDIR D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3
    210         @endcode
    211         Also, add the built binary files path to the system path by using the [PathEditor](http://www.redfernplace.com/software-projects/patheditor/). In our
    212         case this is `D:/OpenCV/dep/qt/qt-everywhere-opensource-src-4.7.3/bin`.
    213 
    214         @note
    215         If you plan on doing Qt application development you can also install at this point the *Qt
    216         Visual Studio Add-in*. After this you can make and build Qt applications without using the *Qt
    217         Creator*. Everything is nicely integrated into Visual Studio.
    218 
    219 -#  Now start the *CMake (cmake-gui)*. You may again enter it in the start menu search or get it
    220     from the All Programs --\> CMake 2.8 --\> CMake (cmake-gui). First, select the directory for the
    221     source files of the OpenCV library (1). Then, specify a directory where you will build the
    222     binary files for OpenCV (2).
    223 
    224     ![](images/CMakeSelectBin.jpg)
    225 
    226     Press the Configure button to specify the compiler (and *IDE*) you want to use. Note that in
    227     case you can choose between different compilers for making either 64 bit or 32 bit libraries.
    228     Select the one you use in your application development.
    229 
    230     ![](images/CMake_Configure_Windows.jpg)
    231 
    232     CMake will start out and based on your system variables will try to automatically locate as many
    233     packages as possible. You can modify the packages to use for the build in the WITH --\> WITH_X
    234     menu points (where *X* is the package abbreviation). Here are a list of current packages you can
    235     turn on or off:
    236 
    237     ![](images/CMakeBuildWithWindowsGUI.jpg)
    238 
    239     Select all the packages you want to use and press again the *Configure* button. For an easier
    240     overview of the build options make sure the *Grouped* option under the binary directory
    241     selection is turned on. For some of the packages CMake may not find all of the required files or
    242     directories. In case of these CMake will throw an error in its output window (located at the
    243     bottom of the GUI) and set its field values, to not found constants. For example:
    244 
    245     ![](images/CMakePackageNotFoundWindows.jpg)
    246 
    247     ![](images/CMakeOutputPackageNotFound.jpg)
    248 
    249     For these you need to manually set the queried directories or files path. After this press again
    250     the *Configure* button to see if the value entered by you was accepted or not. Do this until all
    251     entries are good and you cannot see errors in the field/value or the output part of the GUI. Now
    252     I want to emphasize an option that you will definitely love:
    253     ENABLE --\> ENABLE_SOLUTION_FOLDERS. OpenCV will create many-many projects and turning this
    254     option will make sure that they are categorized inside directories in the *Solution Explorer*.
    255     It is a must have feature, if you ask me.
    256 
    257     ![](images/CMakeBuildOptionsOpenCV.jpg)
    258 
    259     Furthermore, you need to select what part of OpenCV you want to build.
    260 
    261     -   *BUILD_DOCS* -\> It creates two projects for building the documentation of OpenCV (there
    262         will be a separate project for building the HTML and the PDF files). Note that these aren't
    263         built together with the solution. You need to make an explicit build project command on
    264         these to do so.
    265     -   *BUILD_EXAMPLES* -\> OpenCV comes with many example applications from which you may learn
    266         most of the libraries capabilities. This will also come handy to easily try out if OpenCV is
    267         fully functional on your computer.
    268     -   *BUILD_PACKAGE* -\> Prior to version 2.3 with this you could build a project that will
    269         build an OpenCV installer. With this you can easily install your OpenCV flavor on other
    270         systems. For the latest source files of OpenCV it generates a new project that simply
    271         creates zip archive with OpenCV sources.
    272     -   *BUILD_SHARED_LIBS* -\> With this you can control to build DLL files (when turned on) or
    273         static library files (\*.lib) otherwise.
    274     -   *BUILD_TESTS* -\> Each module of OpenCV has a test project assigned to it. Building these
    275         test projects is also a good way to try out, that the modules work just as expected on your
    276         system too.
    277     -   *BUILD_PERF_TESTS* -\> There are also performance tests for many OpenCV functions. If
    278         you're concerned about performance, build them and run.
    279     -   *BUILD_opencv_python* -\> Self-explanatory. Create the binaries to use OpenCV from the
    280         Python language.
    281 
    282     Press again the *Configure* button and ensure no errors are reported. If this is the case you
    283     can tell CMake to create the project files by pushing the *Generate* button. Go to the build
    284     directory and open the created **OpenCV** solution. Depending on just how much of the above
    285     options you have selected the solution may contain quite a lot of projects so be tolerant on the
    286     IDE at the startup. Now you need to build both the *Release* and the *Debug* binaries. Use the
    287     drop-down menu on your IDE to change to another of these after building for one of them.
    288 
    289     ![](images/ChangeBuildVisualStudio.jpg)
    290 
    291     In the end you can observe the built binary files inside the bin directory:
    292 
    293     ![](images/OpenCVBuildResultWindows.jpg)
    294 
    295     For the documentation you need to explicitly issue the build commands on the *doc* project for
    296     the PDF files and on the *doc_html* for the HTML ones. Each of these will call *Sphinx* to do
    297     all the hard work. You can find the generated documentation inside the `Build/Doc/_html` for the
    298     HTML pages and within the `Build/Doc` the PDF manuals.
    299 
    300     ![](images/WindowsBuildDoc.png)
    301 
    302     To collect the header and the binary files, that you will use during your own projects, into a
    303     separate directory (simillary to how the pre-built binaries ship) you need to explicitely build
    304     the *Install* project.
    305 
    306     ![](images/WindowsBuildInstall.png)
    307 
    308     This will create an *Install* directory inside the *Build* one collecting all the built binaries
    309     into a single place. Use this only after you built both the *Release* and *Debug* versions.
    310 
    311     To test your build just go into the `Build/bin/Debug` or `Build/bin/Release` directory and start
    312     a couple of applications like the *contours.exe*. If they run, you are done. Otherwise,
    313     something definitely went awfully wrong. In this case you should contact us at our [Q&A forum](http://answers.opencv.org/).
    314     If everything is okay the *contours.exe* output should resemble the following image (if
    315     built with Qt support):
    316 
    317     ![](images/WindowsQtContoursOutput.png)
    318 
    319 @note
    320    If you use the GPU module (CUDA libraries) make sure you also upgrade to the latest drivers of
    321     your GPU. Error messages containing invalid entries in (or cannot find) the nvcuda.dll are
    322     caused mostly by old video card drivers. For testing the GPU (if built) run the
    323     *performance_gpu.exe* sample application.
    324 
    325 Set the OpenCV enviroment variable and add it to the systems path {#tutorial_windows_install_path}
    326 =================================================================
    327 
    328 First we set an enviroment variable to make easier our work. This will hold the build directory of
    329 our OpenCV library that we use in our projects. Start up a command window and enter:
    330 @code
    331     setx -m OPENCV_DIR D:\OpenCV\Build\x86\vc10     (suggested for Visual Studio 2010 - 32 bit Windows)
    332     setx -m OPENCV_DIR D:\OpenCV\Build\x64\vc10     (suggested for Visual Studio 2010 - 64 bit Windows)
    333 
    334     setx -m OPENCV_DIR D:\OpenCV\Build\x86\vc11     (suggested for Visual Studio 2012 - 32 bit Windows)
    335     setx -m OPENCV_DIR D:\OpenCV\Build\x64\vc11     (suggested for Visual Studio 2012 - 64 bit Windows)
    336 @endcode
    337 Here the directory is where you have your OpenCV binaries (*extracted* or *built*). You can have
    338 different platform (e.g. x64 instead of x86) or compiler type, so substitute appropriate value.
    339 Inside this you should have two folders called *lib* and *bin*. The -m should be added if you wish
    340 to make the settings computer wise, instead of user wise.
    341 
    342 If you built static libraries then you are done. Otherwise, you need to add the *bin* folders path
    343 to the systems path. This is because you will use the OpenCV library in form of *"Dynamic-link
    344 libraries"* (also known as **DLL**). Inside these are stored all the algorithms and information the
    345 OpenCV library contains. The operating system will load them only on demand, during runtime.
    346 However, to do this the operating system needs to know where they are. The systems **PATH** contains
    347 a list of folders where DLLs can be found. Add the OpenCV library path to this and the OS will know
    348 where to look if he ever needs the OpenCV binaries. Otherwise, you will need to copy the used DLLs
    349 right beside the applications executable file (*exe*) for the OS to find it, which is highly
    350 unpleasent if you work on many projects. To do this start up again the [PathEditor](http://www.redfernplace.com/software-projects/patheditor/) and add the
    351 following new entry (right click in the application to bring up the menu):
    352 @code
    353     %OPENCV_DIR%\bin
    354 @endcode
    355 
    356 ![](images/PathEditorOpenCVInsertNew.png)
    357 
    358 ![](images/PathEditorOpenCVSetPath.png)
    359 
    360 Save it to the registry and you are done. If you ever change the location of your build directories
    361 or want to try out your applicaton with a different build all you will need to do is to update the
    362 OPENCV_DIR variable via the *setx* command inside a command window.
    363 
    364 Now you can continue reading the tutorials with the @ref tutorial_windows_visual_studio_Opencv section.
    365 There you will find out how to use the OpenCV library in your own projects with the help of the
    366 Microsoft Visual Studio IDE.
    367