| --- |
| title: Installation |
| --- |
| |
| # Installation |
|
|
| Prior to installing, have a glance through this guide and take note of the details for your platform. |
| We install and run Caffe on Ubuntu 16.04–12.04, OS X 10.11–10.8, and through Docker and AWS. |
| The official Makefile and `Makefile.config` build are complemented by a [community CMake build](#cmake-build). |
|
|
| **Step-by-step Instructions**: |
|
|
| - [Docker setup](https://github.com/BVLC/caffe/tree/master/docker) *out-of-the-box brewing* |
| - [Ubuntu installation](install_apt.html) *the standard platform* |
| - [Debian installation](install_apt_debian.html) *install caffe with a single command* |
| - [OS X installation](install_osx.html) |
| - [RHEL / CentOS / Fedora installation](install_yum.html) |
| - [Windows](https://github.com/BVLC/caffe/tree/windows) *see the Windows branch led by Guillaume Dumont* |
| - [OpenCL](https://github.com/BVLC/caffe/tree/opencl) *see the OpenCL branch led by Fabian Tschopp* |
| - [AWS AMI](https://aws.amazon.com/marketplace/pp/B01M0AXXQB) *official deep learning amazon machine image from AWS* |
|
|
| **Overview**: |
|
|
| - [Prerequisites](#prerequisites) |
| - [Compilation](#compilation) |
| - [Hardware](#hardware) |
|
|
| When updating Caffe, it's best to `make clean` before re-compiling. |
|
|
| ## Prerequisites |
|
|
| Caffe has several dependencies: |
|
|
| * [CUDA](https://developer.nvidia.com/cuda-zone) is required for GPU mode. |
| * library version 7+ and the latest driver version are recommended, but 6.* is fine too |
| * 5.5, and 5.0 are compatible but considered legacy |
| * [BLAS](http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms) via ATLAS, MKL, or OpenBLAS. |
| * [Boost](http://www.boost.org/) >= 1.55 |
| * `protobuf`, `glog`, `gflags`, `hdf5` |
|
|
| Optional dependencies: |
|
|
| * [OpenCV](http://opencv.org/) >= 2.4 including 3.0 |
| * IO libraries: `lmdb`, `leveldb` (note: leveldb requires `snappy`) |
| * cuDNN for GPU acceleration (v7) |
|
|
| Pycaffe and Matcaffe interfaces have their own natural needs. |
|
|
| * For Python Caffe: `Python 2.7` or `Python 3.3+`, `numpy (>= 1.7)`, boost-provided `boost.python` |
| * For MATLAB Caffe: MATLAB with the `mex` compiler. |
|
|
| **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. |
|
|
| **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. |
|
|
| ### CUDA and BLAS |
|
|
| Caffe requires the CUDA `nvcc` compiler to compile its GPU code and CUDA driver for GPU operation. |
| 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. |
|
|
| 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`. |
|
|
| Caffe requires BLAS as the backend of its matrix and vector computations. |
| There are several implementations of this library. The choice is yours: |
|
|
| * [ATLAS](http://math-atlas.sourceforge.net/): free, open source, and so the default for Caffe. |
| * [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. |
| 1. Install MKL. |
| 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* |
| 3. Set `BLAS := mkl` in `Makefile.config` |
| * [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. |
| 1. Install OpenBLAS |
| 2. Set `BLAS := open` in `Makefile.config` |
|
|
| ### Python and/or MATLAB Caffe (optional) |
|
|
| #### Python |
|
|
| The main requirements are `numpy` and `boost.python` (provided by boost). `pandas` is useful too and needed for some examples. |
|
|
| You can install the dependencies with |
|
|
| pip install -r requirements.txt |
| |
| 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. |
|
|
| 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! |
|
|
| *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.* |
|
|
| #### MATLAB |
|
|
| Install MATLAB, and make sure that its `mex` is in your `$PATH`. |
|
|
| *Caffe's MATLAB interface works with versions 2015a, 2014a/b, 2013a/b, and 2012b.* |
|
|
| ## Compilation |
|
|
| Caffe can be compiled with either Make or CMake. Make is officially supported while CMake is supported by the community. |
|
|
| ### Compilation with Make |
|
|
| 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. |
|
|
| cp Makefile.config.example Makefile.config |
| # Adjust Makefile.config (for example, if using Anaconda Python, or if cuDNN is desired) |
| make all |
| make test |
| make runtest |
| |
| - For CPU & GPU accelerated Caffe, no changes are needed. |
| - 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. |
| - For CPU-only Caffe, uncomment `CPU_ONLY := 1` in `Makefile.config`. |
|
|
| To compile the Python and MATLAB wrappers do `make pycaffe` and `make matcaffe` respectively. |
| Be sure to set your MATLAB and Python paths in `Makefile.config` first! |
|
|
| **Distribution**: run `make distribute` to create a `distribute` directory with all the Caffe headers, compiled libraries, binaries, etc. needed for distribution to other machines. |
|
|
| **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). |
|
|
| 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). |
|
|
| ### CMake Build |
|
|
| 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. |
| The basic steps are as follows: |
|
|
| mkdir build |
| cd build |
| cmake .. |
| make all |
| make install |
| make runtest |
| |
| See [PR #1667](https://github.com/BVLC/caffe/pull/1667) for options and details. |
|
|
| ## Hardware |
|
|
| **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. |
|
|
| **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. |
|
|
| Once installed, check your times against our [reference performance numbers](performance_hardware.html) to make sure everything is configured properly. |
|
|
| Ask hardware questions on the [caffe-users group](https://groups.google.com/forum/#!forum/caffe-users). |
|
|
