Installation Guide

This page gives instructions of how to build and install the mxnet package from scratch on various systems. It consists of two steps, first we build the shared library from the C++ codes (libmxnet.so for linux/osx and libmxnet.dll for windows). Then we install the language, e.g. Python, packages. If the instructions on this page do not work for you, please feel free to ask questions at mxnet/issues, or even better to send pull request if you can fix the problem.

Build the Shared Library

Our goal is to build the shared library:

  • On Linux/OSX the target library is libmxnet.so
  • On Windows the target libary is libmxnet.dll

The minimal building requirement is

  • A recent c++ compiler supporting C++ 11 such as g++ >= 4.8 or clang
  • A BLAS library, such as libblas, libblas, openblas intel mkl

Optional libraries

  • CUDA Toolkit >= v7.0 to run on nvidia GPUs
    • Requires GPU with support for Compute Capability >= 2.0
  • CUDNN to accelerate the GPU computation
  • opencv for image augmentation

We can edit make/config.mk to change the compile options, and then build by make. If everything goes well, we can go the language package installation step.

On the remaining of this section, we provide instructions to install the dependencies and build mxnet from scratch for various systems.

Building on Ubuntu/Debian

On Ubuntu >= 13.10, one can install the dependencies by

sudo apt-get update
sudo apt-get install -y build-essential git libatlas-base-dev libopencv-dev

Then build mxnet

git clone --recursive https://github.com/dmlc/mxnet
cd mxnet; make -j4

Building on OSX

On OSX, we can install the dependencies by

brew update
brew tap homebrew/science
brew info opencv
brew install opencv

Then build mxnet

git clone --recursive https://github.com/dmlc/mxnet
cd mxnet; cp make/osx.mk ./config.mk; make -j4

Troubleshooting:

Some of the users might meet the link error ld: library not found for -lgomp, indicating that the GNU implementation of OpenMP is not in the library path of operating system.

To resolve this issue, run the following commands:

sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.locate.plist # this creates the locate database if it does not exist

locate libgomp.dylib #copy the path which is generated by this command, say path1

ln -s path1 /usr/local/lib/libgomp.dylib

then run make -j4 again.

Building on Windows

Firstly, we should make your Visual Studio 2013 support more C++11 features.

  • Download and install Visual C++ Compiler Nov 2013 CTP.
  • Copy all files in C:\Program Files (x86)\Microsoft Visual C++ Compiler Nov 2013 CTP (or the folder where you extracted the zip archive) to C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC and overwrite all existed files. Don’t forget to backup the original files before copying.

Secondly, fetch the third-party libraries, including OpenCV, CuDNN and OpenBlas(ignore this if you have MKL).

  • NOTICE: You need to register as a NVIDIA community user to get the download link of CuDNN.

Finally, use CMake to create a Visual Studio solution in ./build/. During configuration, you may need to set the path of each third-party library, until no error is reported. (Set environmental variable OpenBLAS_HOME to the OpenBLAS directory containing include and lib; set OpenCV_DIR to the build directory after unpacking the OpenCV package.) Open the solution and compile, you will get a mxnet.dll in ./build/Release or ./build/Debug.

Installing pre-built packages on Windows

Mxnet also provides pre-built packages on Windows. The pre-built package includes pre-build MxNet library, the dependent thrid-party libraries, a sample C++ solution in Visual Studio and the Python install script.

You can download the packages from the Releases tab of MxNet. There are two variants provided: one with GPU support (using CUDA and CUDNN v3) and one without GPU support. You can choose one that fits your hardward configuration.

After download, unpack the package into a folder, say D:\MxNet, then install the package by double clicking the setupenv.cmd inside the folder. It will setup environmental variables needed by MxNet. After that, you should be able to usee the provided VS solution to build C++ programs, or to install Python package.

Customized Building

The configuration of mxnet can be modified by config.mk

  • modify the compiling options such as compilers, CUDA, CUDNN, Intel MKL, various distributed filesystem such as HDFS/Amazon S3/...
  • First copy make/config.mk to the project root, on which any local modification will be ignored by git, then modify the according flags.

Building with Intel MKL Support

First, source /path/to/intel/bin/compilervars.sh to automatically set environment variables. Then, edit make/config.mk, let USE_BLAS = mkl. USE_INTEL_PATH = NONE is usually not necessary to be modified.

Python Package Installation

The python package is located at mxnet/python. It requires python>=2.7 and numpy. To install the latter, if pip is available, then

sudo pip install numpy

otherwise use your package manager, e.g.

sudo apt-get install python-numpy # for debian
sudo yum install python-numpy # for redhat

To have a quick test of the python package, we can train a MLP on the mnist dataset:

python example/image-classification/train_mnist.py

or train a convolution neural network using GPU 0 if we set USE_CUDA=1 during compiling:

python example/image-classification/train_mnist.py --network lenet --gpus 0

There are several ways to install the package:

  1. Install system-widely, which requires root permission

    cd python; sudo python setup.py install

    You will however need Python distutils module for this to work. It is often part of the core python package or it can be installed using your package manager, e.g. in Debian use

    sudo apt-get install python-setuptools

  2. Only set the environment variable PYTHONPATH to tell python where to find the library. For example, assume we cloned mxnet on the home directory ~. then we can added the following line in ~/.bashrc It is recommended for developers who may change the codes. The changes will be immediately reflected once you pulled the code and rebuild the project (no need to call setup again)

    export PYTHONPATH=~/mxnet/python

  3. Install only for the current user.

    cd python; python setup.py develop --user

  4. Copy the package into the working directory which contains the mxnet application programs. In this approach we don’t need to change the system, and therefore is recommended for distributed training.

    Assume we are on the working directory, and mxnet is cloned on the home directory ~.

    cp -r ~/mxnet/python/mxnet .
cp ~/mxnet/lib/libmxnet.so mxnet/

R Package Installation

For Windows/Mac users, we provide pre-built binary package using CPU. You can install weekly updated package directly in R console:

install.packages("drat", repos="https://cran.rstudio.com")
drat:::addRepo("dmlc")
install.packages("mxnet")

To install the R package. First finish the Build MXNet Library step. Then use the following command to install dependencies and build the package at root folder

Rscript -e "install.packages('devtools', repo = 'https://cran.rstudio.com')"
cd R-package
Rscript -e "library(devtools); library(methods); options(repos=c(CRAN='https://cran.rstudio.com')); install_deps(dependencies = TRUE)"
cd ..
make rpkg

Now you should have the R package as a tar.gz file and you can install it as a normal package by (the version number might be different)

R CMD INSTALL mxnet_0.5.tar.gz

Note on Library Build:

We isolate the library build with Rcpp end to maximize the portability

  • MSVC is needed on windows to build the mxnet library, because of CUDA compatiblity issue of toolchains.

Julia Package Installation

The Julia package is hosted in a separate repository MXNet.jl. To use the Julia binding with an existing libmxnet installation, set the following environment variable

export MXNET_HOME=/path/to/libmxnet

The path should be the root directory of libmxnet, in other words, libmxnet.so should be found at $MXNET_HOME/lib. You might want to add it to your .bashrc. Then the Julia package could be installed via

Pkg.add("MXNet")

in a Julia console. For more details, please refer to the full documentation of MXNet.jl.

Scala Package Installation

For Linux/Mac users, we provide pre-built binary packages, with GPU or CPU-only supported. You can use the following dependency in maven, change the artifactId according to your own architecture, e.g., mxnet-full_2.10-osx-x86_64-cpu for OSX (and cpu-only).

<dependency>
  <groupId>ml.dmlc.mxnet</groupId>
  <artifactId>mxnet-full_2.10-linux-x86_64-gpu</artifactId>
  <version>0.1.1</version>
</dependency>

In case your native environment is slightly different from which the assembly package provides, e.g., you use openblas instead of atlas, a more recommended way is to use mxnet-core and put the compiled Java native library somewhere in your load path.

<dependency>
  <groupId>ml.dmlc.mxnet</groupId>
  <artifactId>mxnet-core_2.10</artifactId>
  <version>0.1.1</version>
</dependency>

To build with your own environment. First finish the Build MXNet Library step. Then run following command from the root directory.

make scalapkg

Now you will find jars for assembly, core and example modules. Also it produces the native library in native/{your-architecture}/target, which you can use to cooperate with the core module.

To install the scala package into your local maven repository, run

make scalainstall

Docker Images

Builds of MXNet are available as Docker images: MXNet Docker (CPU) or MXNet Docker (CUDA). These are updated on a weekly basis with the latest builds of MXNet. Examples of running bash in a Docker container are as follows:

sudo docker run -it kaixhin/mxnet
sudo docker run -it --device /dev/nvidiactl --device /dev/nvidia-uvm --device /dev/nvidia0 kaixhin/cuda-mxnet:7.0

For a guide to Docker, see the official docs. For more details on how to use the MXNet Docker images, including requirements for CUDA support, consult the source project.

© 2015-2016 DMLC. All rights reserved.