docs/installation.md

   1 ---
   2 layout: default
   3 title: Caffe
   4 ---
   5
   6 # Installation
   7
   8 Prior to installing, it is best to read through this guide and take note of the details for your platform.
   9 We have installed Caffe on Ubuntu 14.04, Ubuntu 12.04, OS X 10.9, and OS X 10.8.
  10
  11 - [Prerequisites](#prerequisites)
  12 - [Compilation](#compilation)
  13 - [Hardware questions](#hardware_questions)
  14
  15 ## Prerequisites
  16
  17 Caffe depends on several software packages.
  18
  19 * [CUDA](https://developer.nvidia.com/cuda-zone) library version 6.0, 5.5, or 5.0 and the latest driver version for CUDA 6 or 319.* for CUDA 5 (and NOT 331.*)
  20 * [BLAS](http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms) (provided via ATLAS, MKL, or OpenBLAS).
  21 * [OpenCV](http://opencv.org/).
  22 * [Boost](http://www.boost.org/) (>= 1.55, although only 1.55 is tested)
  23 * `glog`, `gflags`, `protobuf`, `leveldb`, `snappy`, `hdf5`, `lmdb`
  24 * For the Python wrapper
  25     * `Python 2.7`, `numpy (>= 1.7)`, boost-provided `boost.python`
  26 * For the MATLAB wrapper
  27     * MATLAB with the `mex` compiler.
  28
  29 **CPU-only Caffe**: for cold-brewed CPU-only Caffe uncomment the `CPU_ONLY := 1` in `Makefile.config` to configure and build Caffe without CUDA. This is helpful for cloud or cluster deployment.
  30
  31 ### CUDA and BLAS
  32
  33 Caffe requires the CUDA `nvcc` compiler to compile its GPU code and CUDA driver for GPU operation.
  34 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.
  35
  36 Caffe requires BLAS as the backend of its matrix and vector computations.
  37 There are several implementations of this library.
  38 The choice is yours:
  39
  40 * [ATLAS](http://math-atlas.sourceforge.net/): free, open source, and so the default for Caffe.
  41     + Ubuntu: `sudo apt-get install libatlas-base-dev`
  42     + CentOS/RHEL: `sudo yum install libatlas-devel`
  43     + OS X: already installed as the [Accelerate / vecLib Framework](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man7/Accelerate.7.html).
  44 * [Intel MKL](http://software.intel.com/en-us/intel-mkl): commercial and optimized for Intel CPUs, with a free trial and [student](http://software.intel.com/en-us/intel-education-offerings) licenses.
  45     1. Install MKL.
  46     2. Set `BLAS := mkl` in `Makefile.config`
  47 * [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.
  48     1. Install OpenBLAS
  49     2. Set `BLAS := open` in `Makefile.config`
  50
  51 ### Python and/or MATLAB wrappers (optional)
  52
  53 #### Python
  54
  55 The main requirements are `numpy` and `boost.python` (provided by boost). `pandas` is useful too and needed for some examples.
  56
  57 You can install the dependencies with
  58
  59     pip install -r /path/to/caffe/python/requirements.txt
  60
  61 but we highly recommend 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.
  62
  63 For **Ubuntu**, if you use the default Python you will need to `apt-get install` the `python-dev` package to have the Python headers for building the wrapper.
  64
  65 For **OS X**, Anaconda is the preferred Python. If you decide against it, please use Homebrew -- but beware of potential linking errors!
  66
  67 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!
  68
  69 *Caffe's Python interface works with Python 2.7. Python 3 or earlier Pythons are your own adventure.*
  70
  71 #### MATLAB
  72
  73 Install MATLAB, and make sure that its `mex` is in your `$PATH`.
  74
  75 *Caffe's MATLAB interface works with versions 2012b, 2013a/b, and 2014a.*
  76
  77 ### The rest of the dependencies
  78
  79 #### Linux
  80
  81 On **Ubuntu**, most of the dependencies can be installed with
  82
  83     sudo apt-get install libprotobuf-dev libleveldb-dev libsnappy-dev libopencv-dev libboost-all-dev libhdf5-serial-dev
  84
  85 And on **CentOS / RHEL**, you can install via yum with
  86
  87     sudo yum install protobuf-devel leveldb-devel snappy-devel opencv-devel boost-devel hdf5-devel
  88
  89 and for **Ubuntu 14.04** the rest of the dependencies can be installed with
  90
  91     sudo apt-get install libgflags-dev libgoogle-glog-dev liblmdb-dev protobuf-compiler
  92
  93 For **Ubuntu 12.04 and CentOS / RHEL** the only exceptions to package installation are the Google flags library, Google logging library, and LMDB. To install these, do:
  94
  95     # glog
  96     wget https://google-glog.googlecode.com/files/glog-0.3.3.tar.gz
  97     tar zxvf glog-0.3.3.tar.gz
  98     cd glog-0.3.3
  99     ./configure
 100     make && make install
 101     # gflags
 102     wget https://github.com/schuhschuh/gflags/archive/master.zip
 103     unzip master.zip
 104     cd gflags-master
 105     mkdir build && cd build
 106     export CXXFLAGS="-fPIC" && cmake .. && make VERBOSE=1
 107     make && make install
 108     # lmdb
 109     git clone git://gitorious.org/mdb/mdb.git
 110     cd mdb/libraries/liblmdb
 111     make && make install
 112
 113 Note that glog does not compile with the most recent gflags version (2.1), so before that is resolved you will need to build with glog first.
 114
 115 #### OS X
 116
 117 On **OS X**, we highly recommend using the [Homebrew](http://brew.sh/) package manager, and ideally starting from a clean install of the OS (or from a wiped `/usr/local`) to avoid conflicts.
 118 In the following, we assume that you're using Anaconda Python and Homebrew.
 119
 120 To install the OpenCV dependency, we'll need to provide an additional source for Homebrew:
 121
 122     brew tap homebrew/science
 123
 124 If using Anaconda Python, a modification is required to the OpenCV formula.
 125 Do `brew edit opencv` and change the lines that look like the two lines below to exactly the two lines below.
 126
 127       -DPYTHON_LIBRARY=#{py_prefix}/lib/libpython2.7.dylib
 128       -DPYTHON_INCLUDE_DIR=#{py_prefix}/include/python2.7
 129
 130 **NOTE**: We find that everything compiles successfully if `$LD_LIBRARY_PATH` is not set at all, and `$DYLD_FALLBACK_LIBRARY_PATH` is set to to provide CUDA, Python, and other relevant libraries (e.g. `/usr/local/cuda/lib:$HOME/anaconda/lib:/usr/local/lib:/usr/lib`).
 131 In other `ENV` settings, things may not work as expected.
 132
 133 #### 10.8-specific Instructions
 134
 135 Simply run the following:
 136
 137     brew install --build-from-source --with-python boost
 138     brew install --with-python protobuf
 139     for x in snappy leveldb gflags glog szip lmdb homebrew/science/opencv; do brew install $x; done
 140
 141 Building boost from source is needed to link against your local Python (exceptions might be raised during some OS X installs, but **ignore** these and continue). If you do not need the Python wrapper, simply doing `brew install boost` is fine.
 142
 143 **Note** that the HDF5 dependency is provided by Anaconda Python in this case.
 144 If you're not using Anaconda, include `hdf5` in the list above.
 145
 146 #### 10.9-specific Instructions
 147
 148 In OS X 10.9, clang++ is the default C++ compiler and uses `libc++` as the standard library.
 149 However, NVIDIA CUDA (even version 6.0) currently links only with `libstdc++`.
 150 This makes it necessary to change the compilation settings for each of the dependencies.
 151
 152 We do this by modifying the Homebrew formulae before installing any packages.
 153 Make sure that Homebrew doesn't install any software dependencies in the background; all packages must be linked to `libstdc++`.
 154
 155 The prerequisite Homebrew formulae are
 156
 157     boost snappy leveldb protobuf gflags glog szip lmdb homebrew/science/opencv
 158
 159 For each of these formulas, `brew edit FORMULA`, and add the ENV definitions as shown:
 160
 161       def install
 162           # ADD THE FOLLOWING:
 163           ENV.append "CXXFLAGS", "-stdlib=libstdc++"
 164           ENV.append "CFLAGS", "-stdlib=libstdc++"
 165           ENV.append "LDFLAGS", "-stdlib=libstdc++ -lstdc++"
 166           # The following is necessary because libtool likes to strip LDFLAGS:
 167           ENV["CXX"] = "/usr/bin/clang++ -stdlib=libstdc++"
 168           ...
 169
 170 To edit the formulae in turn, run
 171
 172     for x in snappy leveldb protobuf gflags glog szip boost lmdb homebrew/science/opencv; do brew edit $x; done
 173
 174 After this, run
 175
 176     for x in snappy leveldb protobuf gflags glog szip lmdb homebrew/science/opencv; do brew uninstall $x; brew install --build-from-source --fresh -vd $x; done
 177     brew install --build-from-source --with-python --fresh -vd boost
 178
 179 **Note** that `brew install --build-from-source --fresh -vd boost` is fine if you do not need the Caffe Python wrapper.
 180
 181 **Note** that the HDF5 dependency is provided by Anaconda Python in this case.
 182 If you're not using Anaconda, include `hdf5` in the list above.
 183
 184 **Note** that in order to build the caffe python wrappers you must install boost using the --with-python option:
 185
 186     brew install --build-from-source --with-python --fresh -vd boost
 187
 188 #### Windows
 189
 190 There is an unofficial Windows port of Caffe at [niuzhiheng/caffe:windows](https://github.com/niuzhiheng/caffe). Thanks [@niuzhiheng](https://github.com/niuzhiheng)!
 191
 192 ## Compilation
 193
 194 Now that you have the prerequisites, edit your `Makefile.config` to change the paths for your setup.
 195 The defaults should work, but uncomment the relevant lines if using Anaconda Python.
 196
 197     cp Makefile.config.example Makefile.config
 198     # Adjust Makefile.config (for example, if using Anaconda Python)
 199     make all
 200     make test
 201     make runtest
 202
 203 If there is no GPU in your machine, you should switch to CPU-only Caffe by uncommenting `CPU_ONLY := 1` in `Makefile.config`.
 204
 205 To compile the Python and MATLAB wrappers do `make pycaffe` and `make matcaffe` respectively.
 206 Be sure to set your MATLAB and Python paths in `Makefile.config` first!
 207
 208 *Distribution*: run `make distribute` to create a `distribute` directory with all the Caffe headers, compiled libraries, binaries, etc. needed for distribution to other machines.
 209
 210 *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).
 211
 212 Now that you have installed Caffe, check out the [MNIST demo](mnist.html) and the pretrained [ImageNet example](imagenet.html).
 213
 214 ## Hardware Questions
 215
 216 **Laboratory Tested Hardware**: Berkeley Vision runs Caffe with K40s, K20s, and Titans including models at ImageNet/ILSVRC scale. We also run on GTX series cards and GPU-equipped MacBook Pros. 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.
 217
 218 **CUDA compute capability**: devices with compute capability <= 2.0 may have to reduce CUDA thread numbers and batch sizes due to hardware constraints. Your mileage may vary.
 219
 220 Once installed, check your times against our [reference performance numbers](performance_hardware.html) to make sure everything is configured properly.
 221
 222 Refer to the project's issue tracker for [hardware/compatibility](https://github.com/BVLC/caffe/issues?labels=hardware%2Fcompatibility&page=1&state=open).