What operating systems are supported?

Caffe2 is tested on

  • macOS Sierra or above
  • Ubuntu 14.04 and 16.04
  • CentOS 7
  • Windows 10
  • iOS and Android
  • Raspberry Pi
  • Nvidia Tegra

What languages does Caffe2 support?

Caffe2 is written in C++ with a Python frontend. You can find all of the code on our Github page.

How do I use Caffe2 with my GPU?

Many of Caffe2’s operators have CUDA implementations, allowing you to use Caffe2 with your Nvidia GPU. To install Caffe2 with GPU support, first install all the needed Nvidia libraries (CUDA and CuDNN) and then follow the installation instructions.

What are all of these optional libraries used for?

Caffe2 can has many optional dependencies, which extend Caffe2’s core functionality.

cuDNN If using GPU, this is needed for Caffe2’s cuDNN operators
Eigen 3 The default BLAS backend
LevelDB One of the DB options for storing Caffe2 models
Nvidia CUDA v6.5 or greater
OpenCV for image-related operations; requires leveldb <= v1.19
OpenMPI for MPI-related Caffe2 operators, which are used for distributed training
RocksdB for Caffe2’s RocksDB IO backend
ZeroMQ needed for Caffe2’s ZmqDB IO backend (serving data through a socket)
Graphviz Used for plotting in the Jupyter Notebook Tutorials
Hypothesis Used in all of the tests
Jupyter Used for interactive python notebooks
LevelDB One of the DB options for storing Caffe2 models
lmdb One of the DB options for storing Caffe2 models
Matplotlib Used for plotting in the Jupyter Notebook Tutorials
Pydot Used for plotting in the Jupyter Notebook Tutorials
Python-nvd3 Used for plotting in the Jupyter Notebook Tutorials
pyyaml Used in the MNIST tutorial
requests Used in the MNIST tutorial to download the dataset
Scikit-Image Used for image processing
SciPy Used for assorted mathematical operations
ZeroMQ needed for Caffe2’s ZmqDB IO backend (serving data through a socket)

Why do I get import errors in Python when I try to use Caffe2?

You will get errors like ModuleNotFoundError: No module named <packagename> if the Python interpreter that you are running can not find the module that you are trying to import (a Python module is a Python source file or a directory of Python source files). This is always caused by one of the following problems

  1. The needed package is not installed
  2. The needed package is installed in the wrong place
  3. The wrong Python is being used

If you are trying to run a tutorial, then make sure you have installed all of the dependencies at the top of the tutorials page. If you are getting an import error on caffe2 itself, then you might have to set PYTHONPATH, but should understand the following first.

How do Python installations work?

A Python installation consists of a Python executable (just called python) and a corresponding set of directories:

  • lib/ where c and c++ libraries are found (.so and .a extensions on Linux, .dylib extensions on Mac)
  • lib/python2.7/site-packages/ where installed Python modules are found (Python modules are just Python source files)
  • include/ where headers for c and c++ libraries are found
  • bin/ where the Python executable itself is found

Your python installation looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/usr/local/                                     # your python root and CMAKE_INSTALL_PREFIX
  +-- bin/
    +-- python
    +-- <other executables>
  +-- include/
    +-- <header files for c and c++ libraries>
  +-- lib/
    +-- libcaffe2.dylib
    +-- <other Caffe2 c and c++ libraries>
    +-- <other c and c++ libraries>
    +-- python2.7/                              # or python 3.6, or whatever your version is
      +-- site-packages/
        +-- caffe2/                             # where compiled Caffe2 python source files are
        +-- <other installed python modules>

There may be multiple Python installations on your machine, but only one should be active at a time. Your current Python root is at “$(which python)/../..” . If you are using a conda environment then it will be <Anaconda root directory>/envs/<conda env name> instead of /usr/local/ . If you are using Anaconda but not an environment, then it will be your Anaconda root directory instead of /usr/local/.

Note: pip will only install into the current environment if which pip is in the same directory as which python. conda will only install into the current environment if which conda is in the same directory as which python. Otherwise, these tools will install into unexpected places that will probably not work correctly.

When Python imports anything, it first looks in its own site-packages directory and then looks in all directories in the PYTHONPATH environment variable. If you are having trouble importing Caffe2 in python, then:

  1. Make sure that you are using the same python that was used to build Caffe2. If you installed or uninstalled a new version of python or Anaconda since building Caffe2 then your python may have changed. If you are using Anaconda, make sure you are using the same conda environment that was used to build Caffe2.
  2. If Caffe2 is installed into the correct site-packages (the directory structure looks like it does above) and python can still not import Caffe2, then add the current python root to PYTHONPATH by running export PYTHONPATH="${PYTHONPATH}:$(which python)/../.. and try again.

If you overrode the default CMAKE_INSTALL_PREFIX when you built Caffe2, then you might have to add that to PYTHONPATH as well.

Why is Caffe2 not working as expected in Anaconda?

First read the above section. If you use Anaconda then your python installation is a little more complicated and will look more like

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
~/anaconda2/
  +-- bin/
    +-- python
  +-- include/
  +-- lib/
    +-- <c and c++ libraries installed in the root env>
    +-- python2.7/
      +-- site-packages/
        +-- <python modules installed in the root env>
  +-- envs/
    +-- my_caffe2_env/
      +-- bin/
        +-- python
      +-- include/
      +-- lib/
        +-- <c and c++ libraries installed in my_caffe2_env>
        +-- python2.7/
          +-- site-packages/
            +-- <python modules installed in my_caffe2_env>
    +-- <your other conda envs>

Whenever you make a new conda environment with conda create <env_name> then Anaconda adds a new directory ~/anaconda2/envs/<env_name> with its own bin/python, lib/ and python2.7/site-packages/ . This is how Anaconda keeps each environment separate from each other.

Notice that there is still a complete Python installation in the root Anaconda directory. This is the “root” or “default” conda environment, and where pip and conda will install packages when you do not have conda environment activated. However, conda envs will also look in the root env if they do not find required modules in their own env. So if you install Protobuf into env my_caffe2_env and also into the root env and install Caffe2 into env my_caffe2_env and then uninstall Protobuf from my_caffe2_env, then Caffe2 will start using the Protobuf from your root env instead. This behaviour is often not what you want and can easily cause version mismatch problems. For this reason we recommend that you avoid installing packages into your root conda environment and install Caffe2 into a brand new conda environment.

Protobuf version mismatch is a common problem. Having different protobuf versions often leads to incompatible headers and libraries. Upgrading to the latest protobuf is not the solution. The version of Protobuf used during compile time must match the one used at runtime.

Run these commands to see which Protobuf version is currently visible on your machine.

1
2
3
which protoc
protoc --version
find $(dirname $(which protoc))/../lib -name 'libproto*'

Now find what Protobuf version your Caffe2 installation expects. First find your Caffe2 library, which can have several possible locations depending on your install environment. Then run the following command with <your libcaffe2> replaced with the location of your Caffe2 library.

For Linux: ldd <your libcaffe2> For macOS: otool -L <your libcaffe2>

You need the Protobuf versions to match.

For example, on a Mac you might find that your current visible Protobuf is:

1
2
3
4
5
6
7
8
9
10
$ which protoc
/usr/local/bin/protoc
$ protoc --version
libprotoc 3.5.1
$ otool -L /usr/local/lib/libprotobuf.dylib
/usr/local/lib/libprotobuf.dylib:
	/usr/local/opt/protobuf/lib/libprotobuf.15.dylib (compatibility version 16.0.0, current version 16.1.0)
	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.11)
	/usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 400.9.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1252.0.0)

but that your Caffe2 installation expects

1
2
3
4
5
$ otool -L /usr/local/lib/libcaffe2.dylib
@rpath/libcaffe2.dylib (compatibility version 0.0.0, current version 0.0.0)
	@rpath/libprotobuf.14.dylib (compatibility version 15.0.0, current version 15.0.0)
	/usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 400.9.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1252.0.0)

This example would lead to Protobuf errors, as libprotobuf.14.dylib which Caffe2 expects is not the same as libprotobuf.15.dylib which exists on the machine. In this example, the Protobuf on the machine will have to be downgraded to 3.4.1.

How can I find a file, library, or package on my computer?

Find libraries, binaries, and other files with the find command. On Macs and Linux, the conventional name of a library for a package mypackage is libmypackage.a or libmypackage.dylib. find accepts wildcards * that match any string of any length. For example

1
2
3
4
5
# Find everything associated with protobuf anywhere
find / -name *protobuf* 2>/dev/null

# Find all protobuf libraries everywhere
find / -name libprotobuf* 2>/dev/null

Use which in combination with the --version flag to find out more about executables on your system. For example

1
2
3
4
5
which python
python --version

which protoc
protoc --version

How can I find what dependencies my Caffe2 library (or other library) has?

For Linux, Ubuntu and CentOS

Use ldd <path to a library> on libraries (files that end in .so) to find out what other libraries it needs and where it expects to find them. You can find where libraries are with the find command above.

For macOS

Use otool -L <path to a library> on libraries (files that end in .dylib) to find out what other libraries it needs and where it expects to find them. Libraries are usually installed under /usr/lib, or /usr/local/lib (for Homebrew), or alongside a Python installation. You can find where libraries are with the find command above.

For example:

1
2
3
4
5
6
7
8
9
$ otool -L ~/anaconda3/envs/my_caffe2_env/lib/libcaffe2.dylib
/Users/my_username/anaconda3/envs/my_caffe2_env/lib/libcaffe2.dylib:
	@rpath/libcaffe2.dylib (compatibility version 0.0.0, current version 0.0.0)
	/usr/local/lib/libprotobuf.14.dylib (compatibility version 15.0.0, current version 15.0.0)
	@rpath/libmkl_rt.dylib (compatibility version 0.0.0, current version 0.0.0)
	@rpath/libgflags.2.2.dylib (compatibility version 2.2.0, current version 2.2.1)
	/usr/local/lib/libglog.0.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 400.9.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1252.0.0)

To find out what “@rpath” is, run otool with -l (lowercase L) and pipe that into grep LC_RPATH -A 3, e.g.

1
2
3
4
$ otool -l ~/anaconda3/envs/my_caffe2_env/lib/libcaffe2.dylib | grep LC_RPATH -A 3
          cmd LC_RPATH
      cmdsize 32
         path @loader_path/ (offset 12)

In this example, @rpath will evaluate to @loader_path, which is essentially the location of the library that you ran otool on (see dyld). So, in this example, libcaffe2.dylib will look for libgflags.2.2.dylib in the same folder that libcaffe2.dylib is in.

The source directory does not contain a CMakeLists.txt file

You need to run git submodule update --init in the Caffe2 root directory.

No module named caffe2_pybind11_state_gpu

If you are not building for GPU then ignore this. If you are building for GPU, then make sure CUDA was found correctly in the output of the cmake command that was run to build Caffe2.

My python kernel keeps crashing when using Jupyter

This happens when you try to call Jupyter server directly (like in a Docker container). Use sh -c "jupyter notebook ..." to get around this problem.

I still have a question, where can I get more help?

For further issues, please post a new issue to our issue tracker on Github.

If your question is about an error installing Caffe2, then please include the following information in your issue:

  • $(uname -a)
  • Which installation guide you followed.
  • What flags you passed to cmake
  • The full output of your cmake command

Miscellaneous errors

  • On Mac, you may need to install Xcode or at a minimum xcode command line tools. You can install it by running xcode-select --install
  • If you experience errors related to confu or PeachPy when running make install, then install dependencies of NNPACK: [sudo] pip install --upgrade git+https://github.com/Maratyszcza/PeachPy and [sudo] pip install --upgrade git+https://github.com/Maratyszcza/confu
  • If you get model downloading errors when running in sudo, then PYTHONPATH might not be visible in that context. Run sudo visudo then add this line: Defaults env_keep += "PYTHONPATH"
  • If you encounter “AttributeError: ‘module’ object has no attribute ‘MakeArgument’” when calling core.CreateOperator then try removing caffe2/python/utils from the directory that you installed Caffe2 in.
  • If you see errors with libdc1394 when opencv is installed, then run ln /dev/null /dev/raw1394 . That solution is not persistent so try sh -c 'ln -s /dev/null /dev/raw1394' or when instantiating the container use: --device /dev/null:/dev/raw1394

Edit on GitHub