docs/installation.md

   1 ---
   2 title: Installation
   3 ---
   4
   5 # Installation
   6
   7 Prior to installing, have a glance through this guide and take note of the details for your platform.
   8 We install and run Caffe on Ubuntu 16.04–12.04, OS X 10.11–10.8, and through Docker and AWS.
   9 The official Makefile and `Makefile.config` build are complemented by a [community CMake build](#cmake-build).
  10
  11 **Step-by-step Instructions**:
  12
  13 - [Docker setup](https://github.com/BVLC/caffe/tree/master/docker) *out-of-the-box brewing*
  14 - [Ubuntu installation](install_apt.html) *the standard platform*
  15 - [Debian installation](install_apt_debian.html) *install caffe with a single command*
  16 - [OS X installation](install_osx.html)
  17 - [RHEL / CentOS / Fedora installation](install_yum.html)
  18 - [Windows](https://github.com/BVLC/caffe/tree/windows) *see the Windows branch led by Guillaume Dumont*
  19 - [OpenCL](https://github.com/BVLC/caffe/tree/opencl) *see the OpenCL branch led by Fabian Tschopp*
  20 - [AWS AMI](https://github.com/bitfusionio/amis/tree/master/awsmrkt-bfboost-ubuntu14-cuda75-caffe) *pre-configured for AWS*
  21
  22 **Overview**:
  23
  24 - [Prerequisites](#prerequisites)
  25 - [Compilation](#compilation)
  26 - [Hardware](#hardware)
  27
  28 When updating Caffe, it's best to `make clean` before re-compiling.
  29
  30 ## Prerequisites
  31
  32 Caffe has several dependencies:
  33
  34 * [CUDA](https://developer.nvidia.com/cuda-zone) is required for GPU mode.
  35     * library version 7+ and the latest driver version are recommended, but 6.* is fine too
  36     * 5.5, and 5.0 are compatible but considered legacy
  37 * [BLAS](http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms) via ATLAS, MKL, or OpenBLAS.
  38 * [Boost](http://www.boost.org/) >= 1.55
  39 * `protobuf`, `glog`, `gflags`, `hdf5`
  40
  41 Optional dependencies:
  42
  43 * [OpenCV](http://opencv.org/) >= 2.4 including 3.0
  44 * IO libraries: `lmdb`, `leveldb` (note: leveldb requires `snappy`)
  45 * cuDNN for GPU acceleration (v7)
  46
  47 Pycaffe and Matcaffe interfaces have their own natural needs.
  48
  49 * For Python Caffe:  `Python 2.7` or `Python 3.3+`, `numpy (>= 1.7)`, boost-provided `boost.python`
  50 * For MATLAB Caffe: MATLAB with the `mex` compiler.
  51
  52 **cuDNN Caffe**: for fastest operation Caffe is accelerated by drop-in integration of [NVIDIA cuDNN](https://developer.nvidia.com/cudnn). To speed up your Caffe models, install cuDNN then uncomment the `USE_CUDNN := 1` flag in `Makefile.config` when installing Caffe. Acceleration is automatic. The current version is cuDNN v7; older versions are supported in older Caffe.
  53
  54 **CPU-only Caffe**: for cold-brewed CPU-only Caffe uncomment the `CPU_ONLY := 1` flag in `Makefile.config` to configure and build Caffe without CUDA. This is helpful for cloud or cluster deployment.
  55
  56 ### CUDA and BLAS
  57
  58 Caffe requires the CUDA `nvcc` compiler to compile its GPU code and CUDA driver for GPU operation.
  59 To install CUDA, go to the [NVIDIA CUDA website](https://developer.nvidia.com/cuda-downloads) and follow installation instructions there. Install the library and the latest standalone driver separately; the driver bundled with the library is usually out-of-date. **Warning!** The 331.* CUDA driver series has a critical performance issue: do not use it.
  60
  61 For best performance, Caffe can be accelerated by [NVIDIA cuDNN](https://developer.nvidia.com/cudnn). Register for free at the cuDNN site, install it, then continue with these installation instructions. To compile with cuDNN set the `USE_CUDNN := 1` flag set in your `Makefile.config`.
  62
  63 Caffe requires BLAS as the backend of its matrix and vector computations.
  64 There are several implementations of this library. The choice is yours:
  65
  66 * [ATLAS](http://math-atlas.sourceforge.net/): free, open source, and so the default for Caffe.
  67 * [Intel MKL](http://software.intel.com/en-us/intel-mkl): commercial and optimized for Intel CPUs, with [free](https://registrationcenter.intel.com/en/forms/?productid=2558) licenses.
  68     1. Install MKL.
  69     2. Set up MKL environment (Details: [Linux](https://software.intel.com/en-us/node/528499), [OS X](https://software.intel.com/en-us/node/528659)). Example: *source /opt/intel/mkl/bin/mklvars.sh intel64*
  70     3. Set `BLAS := mkl` in `Makefile.config`
  71 * [OpenBLAS](http://www.openblas.net/): free and open source; this optimized and parallel BLAS could require more effort to install, although it might offer a speedup.
  72     1. Install OpenBLAS
  73     2. Set `BLAS := open` in `Makefile.config`
  74
  75 ### Python and/or MATLAB Caffe (optional)
  76
  77 #### Python
  78
  79 The main requirements are `numpy` and `boost.python` (provided by boost). `pandas` is useful too and needed for some examples.
  80
  81 You can install the dependencies with
  82
  83     pip install -r requirements.txt
  84
  85 but we suggest first installing the [Anaconda](https://store.continuum.io/cshop/anaconda/) Python distribution, which provides most of the necessary packages, as well as the `hdf5` library dependency.
  86
  87 To import the `caffe` Python module after completing the installation, add the module directory to your `$PYTHONPATH` by `export PYTHONPATH=/path/to/caffe/python:$PYTHONPATH` or the like. You should not import the module in the `caffe/python/caffe` directory!
  88
  89 *Caffe's Python interface works with Python 2.7. Python 3.3+ should work out of the box without protobuf support. For protobuf support please install protobuf 3.0 alpha (https://developers.google.com/protocol-buffers/). Earlier Pythons are your own adventure.*
  90
  91 #### MATLAB
  92
  93 Install MATLAB, and make sure that its `mex` is in your `$PATH`.
  94
  95 *Caffe's MATLAB interface works with versions 2015a, 2014a/b, 2013a/b, and 2012b.*
  96
  97 ## Compilation
  98
  99 Caffe can be compiled with either Make or CMake. Make is officially supported while CMake is supported by the community.
 100
 101 ### Compilation with Make
 102
 103 Configure the build by copying and modifying the example `Makefile.config` for your setup. The defaults should work, but uncomment the relevant lines if using Anaconda Python.
 104
 105     cp Makefile.config.example Makefile.config
 106     # Adjust Makefile.config (for example, if using Anaconda Python, or if cuDNN is desired)
 107     make all
 108     make test
 109     make runtest
 110
 111 - For CPU & GPU accelerated Caffe, no changes are needed.
 112 - For cuDNN acceleration using NVIDIA's proprietary cuDNN software, uncomment the `USE_CUDNN := 1` switch in `Makefile.config`. cuDNN is sometimes but not always faster than Caffe's GPU acceleration.
 113 - For CPU-only Caffe, uncomment `CPU_ONLY := 1` in `Makefile.config`.
 114
 115 To compile the Python and MATLAB wrappers do `make pycaffe` and `make matcaffe` respectively.
 116 Be sure to set your MATLAB and Python paths in `Makefile.config` first!
 117
 118 **Distribution**: run `make distribute` to create a `distribute` directory with all the Caffe headers, compiled libraries, binaries, etc. needed for distribution to other machines.
 119
 120 **Speed**: for a faster build, compile in parallel by doing `make all -j8` where 8 is the number of parallel threads for compilation (a good choice for the number of threads is the number of cores in your machine).
 121
 122 Now that you have installed Caffe, check out the [MNIST tutorial](gathered/examples/mnist.html) and the [reference ImageNet model tutorial](gathered/examples/imagenet.html).
 123
 124 ### CMake Build
 125
 126 In lieu of manually editing `Makefile.config` to configure the build, Caffe offers an unofficial CMake build thanks to @Nerei, @akosiorek, and other members of the community. It requires CMake version >= 2.8.7.
 127 The basic steps are as follows:
 128
 129     mkdir build
 130     cd build
 131     cmake ..
 132     make all
 133     make install
 134     make runtest
 135
 136 See [PR #1667](https://github.com/BVLC/caffe/pull/1667) for options and details.
 137
 138 ## Hardware
 139
 140 **Laboratory Tested Hardware**: Berkeley Vision runs Caffe with Titan Xs, K80s, GTX 980s, K40s, K20s, Titans, and GTX 770s including models at ImageNet/ILSVRC scale. We have not encountered any trouble in-house with devices with CUDA capability >= 3.0. All reported hardware issues thus-far have been due to GPU configuration, overheating, and the like.
 141
 142 **CUDA compute capability**: devices with compute capability <= 2.0 may have to reduce CUDA thread numbers and batch sizes due to hardware constraints. Brew with caution; we recommend compute capability >= 3.0.
 143
 144 Once installed, check your times against our [reference performance numbers](performance_hardware.html) to make sure everything is configured properly.
 145
 146 Ask hardware questions on the [caffe-users group](https://groups.google.com/forum/#!forum/caffe-users).