Build Apache MXNet from Source

Building and installing Apache MXNet from source is a three-step process. First, build the shared libmxnet which provides the MXNet backend, then install your preferred language binding and finally validate that MXNet was installed correctly by running a small example.

  1. Obtaining the source
  2. Installing MXNet's recommended dependencies
  3. Overview of optional dependencies and optional features
  4. Building MXNet
  5. Install the language API binding(s) you would like to use for MXNet.

MXNet's newest and most popular API is Gluon. Gluon is built into the Python binding. If Python isn't your preference, you still have more options. MXNet supports several other language bindings. Please see the API Documentation page for an overview of all supported languages and their APIs.

Obtaining the source code

To obtain the source code of the latest Apache MXNet release, please access the Download page and download the .tar.gz source archive corresponding to the release you wish to build.

Developers can also obtain the unreleased development code from the git repository via git clone --recursive https://github.com/apache/mxnet

Building a MXNet 1.x release from source requires a C++11 compliant compiler.

Building the development version of MXNet or any 2.x release from source requires a C++17 compliant compiler. The oldest compiler versions tested during MXNet 2 development are GCC 7, Clang 6 and MSVC 2019.

To install the build tools and recommended dependencies, please run the following commands respectively based on your Operating System. Please see the next section for further explanations on the set of required and optional dependencies of MXNet.

Debian Linux derivatives (Debian, Ubuntu, ...)

git clone --recursive https://github.com/apache/mxnet
cd mxnet
sudo apt-get update
sudo apt-get install -y build-essential git ninja-build ccache libopenblas-dev libopencv-dev cmake

Red Hat Enterprise Linux derivatives (RHEL, CentOS, Fedora, ...)

sudo yum install epel-release centos-release-scl
sudo yum install git make ninja-build automake autoconf libtool protobuf-compiler protobuf-devel \
    atlas-devel openblas-devel lapack-devel opencv-devel openssl-devel zeromq-devel python3 \ 
    devtoolset-7
source /opt/rh/devtoolset-7/enable

Here devtoolset-7 refers to the Developer Toolset 7 created by Red Hat for developers working on CentOS or Red Hat Enterprise Linux platform and providing the GNU Compiler Collection 7.

macOS

# Install OS X Developer Tools
xcode-select --install

# Install Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Install dependencies
brew install cmake ninja ccache opencv

Note: the compiler provided by Apple on macOS does not support OpenMP. To use OpenMP on macOS you need to install for example the Clang compiler via brew:

brew install llvm

Windows

You can use Chocolatey software management solution to install some dependencies on Windows.

choco install python git 7zip cmake ninja opencv

Currently OpenBLAS is not available from Chocolatey. You may download it from from the OpenBLAS release page and compile from source. Set the OpenBLAS_HOME environment variable to point to the OpenBLAS directory that contains the include and lib directories for example by typing set OpenBLAS_HOME=C:\utils\OpenBLAS.

If you like to compile MXNet with Visual Studio compiler, please install at least VS2019.

Overview of optional dependencies and optional features

Math Library Selection

MXNet relies on the BLAS (Basic Linear Algebra Subprograms) library for numerical computations. In addition to BLAS, some operators in MXNet rely on the LAPACK (Linear Algebra Package), an additional set of mathematical functions.

Several BLAS and LAPACK implementations exist. Among them, MXNet is tested with:

Apple Accelerate and MKL are proprietary. ATLAS and OpenBLAS are Open Source. If you don't have any specific requirements, MXNet recommends OpenBLAS as it typically outperforms ATLAS, is portable across many platforms, provides a LAPACK implementation and has a permissive license.

Optional GPU support

MXNet optionally supports NVDIA CUDA and cuDNN for better performance on NVidia devices. MXNet releases in general are tested with the last two major CUDA versions available at the time of the release. For example, CUDA 9.2 and 10.2.

To compile MXNet with CUDA support, define the USE_CUDA option. If you compile MXNet on a system with NVidia GPUs, the build system will automatically detect the CUDA Architecture. If you are compiling on a system without NVidia GPUs, please specify the MXNET_CUDA_ARCH option to select the CUDA Architecture and avoid a lengthy build targeting all common CUDA Architectures. Please see the MXNet build configuration instructions in the next step.

MXNet also supports NCCL - NVIDIA's Collective Communications Library. NCCL is useful when using MXNet on multiple GPUs that require communication. Instructions for installing NCCL are found in the following Build MXNet with NCCL section.

To enable building MXNet with NCCL, install NCCL and define the USE_NCCL option in the MXNet build configuration in the next step.

After building with NCCL, you may optionally use the tests in tests/python/gpu/test_nccl.py to ensure NCCL is enabled correctly. Please first delete the line containing skip(reason="Test requires NCCL library installed and enabled during build") before running the test. In MXNet 2.x versions, the test can be run via pytest --verbose tests/python/gpu/test_nccl.py. In MXNet 1.x it is run via python tests/python/gpu/test_nccl.py.

To get the best performance out of NCCL it is recommended to set environment variable NCCL_LAUNCH_MODE=PARALLEL when using NCCL version 2.1 or newer.

Optional OpenCV support

MXNet's Image Loading and Augmentation features rely on OpenCV. Image Loading and Augmentation

Building MXNet

MXNet 1.x can be built either with a classic Makefile setup or with the cmake cross platform build system. Starting with MXNet 1.7, MXNet recommends using the cmake cross platform build tool.

Note: The cmake build requires CMake 3.13 or higher. If you are running an older version of CMake, you will see an error message like CMake 3.13 or higher is required. You are running version 3.10.2. Please update CMake on your system. You can download and install latest CMake from https://cmake.org or via the Python package manager pip with python3 -m pip install --user --upgrade "cmake>=3.13.2". After installing cmake with pip3, it is usually available at ~/.local/bin/cmake or directly as cmake.

Please see the cmake configuration files files for instructions on how to configure and build MXNet with cmake.

Up to the MXNet 1.6 release, please follow the instructions in the make/config.mk file on how to configure and compile MXNet. This method is supported on all 1.x releases.

To enable the optional MXNet C++ package, please set the USE_CPP_PACKAGE=1 option prior to compiling. See the C++ guide for more information.

Installing MXNet Language Bindings

After building MXNet's shared library, you can install other language bindings.

NOTE: The C++ API binding must be built when you build MXNet from source. See Build MXNet with C++.

Installing Language Packages for MXNet

After you have installed the MXNet core library. You may install MXNet interface packages for the programming language of your choice: - Python - C++ - Clojure - Julia - Perl - R - Scala - Java

Install MXNet for Python

To install the MXNet Python binding navigate to the root of the MXNet folder then run the following:

python3 -m pip install --user -e ./python

Note that the -e flag is optional. It is equivalent to --editable and means that if you edit the source files, these changes will be reflected in the package installed.

You may optionally install graphviz library that is used for visualizing network graphs you build on MXNet. You may also install Jupyter Notebook which is used for running MXNet tutorials and examples.

python3 -m pip install --user graphviz==0.8.4 jupyter

Please also see the MXNet Python API page.

Install the MXNet Package for C++

To enable C++ package, just add USE_CPP_PACKAGE=1 as build option when building the MXNet shared library following the instructions from the previous section.

You can find C++ code examples in the cpp-package/example folder of the MXNet project. The folder contains a README explaining how to build the examples. The predict-cpp explains Image Classification using MXNet's C Predict API.

Please also see the MXNet C++ API page.

Install the MXNet Package for Clojure

Refer to the Clojure setup guide.

Please also see the MXNet Clojure API page.

Install the MXNet Package for Julia

Make sure to install at least Julia 1.0.3.

To use the Julia binding you need to set the MXNET_HOME and LD_LIBRARY_PATH environment variables. For example,

export MXNET_HOME=$HOME/mxnet
export LD_LIBRARY_PATH=$HOME/mxnet/build:$LD_LIBRARY_PATH

Then install MXNet with Julia:

julia --color=yes --project=./ -e \
      'using Pkg; \
       Pkg.develop(PackageSpec(name="MXNet", path = joinpath(ENV["MXNET_HOME"], "julia")))'

Please also see the MXNet Julia API page.

Install the MXNet Package for Perl

Installing perl package dependencies on Debian Linux derivatives (Debian, Ubuntu, ...)

sudo apt-get install libmouse-perl pdl cpanminus swig libgraphviz-perl
cpanm -q -L "${HOME}/perl5" Function::Parameters Hash::Ordered PDL::CCS

Installing perl package dependencies on macOS

brew install swig
sudo sh -c 'curl -L https://cpanmin.us | perl - App::cpanminus'
sudo cpanm -q -n PDL Mouse Function::Parameters Hash::Ordered PDL::CCS

Install the MXNet Package for Perl

After you build the shared library, run the following command from the MXNet source root directory to build the MXNet Perl package:

MXNET_HOME=${PWD}
export LD_LIBRARY_PATH=${MXNET_HOME}/lib
export PERL5LIB=${HOME}/perl5/lib/perl5

cd ${MXNET_HOME}/perl-package/AI-MXNetCAPI/
perl Makefile.PL INSTALL_BASE=${HOME}/perl5
make install

cd ${MXNET_HOME}/perl-package/AI-NNVMCAPI/
perl Makefile.PL INSTALL_BASE=${HOME}/perl5
make install

cd ${MXNET_HOME}/perl-package/AI-MXNet/
perl Makefile.PL INSTALL_BASE=${HOME}/perl5
make install

Please also see the MXNet Perl API page.

Install the MXNet Package for R

To install R and the devtools, run

sudo apt-get update
sudo apt-get install -y r-base-core r-cran-devtools libcairo2-dev libxml2-dev

libxml2-dev is required for the roxygen2 dependency and libcairo2-dev is required for the suggested imager dependency.

To generate documentation, it is also required to install roxygen2.

R
> install.packages("roxygen2")
> Would you like to use a personal library instead?  (y/n) y
> Would you like to create a personal library ... to install packages into?  (y/n) y

Note: To successfully complete the next step, you need a personal R library. If you were able to run install.packages("roxygen2") above, you either had already, or you have successfully created a personal library just now.

To build and install the MXNet-R bindings, run:

make -f R-package/Makefile rpkg

Please also see the MXNet R API page.

Install the MXNet Package for Scala

After building the MXNet shared library, you may simply run the following from the MXNet scala-package folder:

mvn install

This will install both the Java Inference API and the required MXNet-Scala package.

Please also see the MXNet Scala API page.

Install the MXNet Package for Java

After building the MXNet shared library, you may simply run the following from the MXNet scala-package folder:

mvn install

This will install both the Java Inference API and the required MXNet-Scala package.

Please also see the MXNet Java API page.

Contributions

You are more than welcome to contribute easy installation scripts for other operating systems and programming languages. See the community contributions page for further information.

Next Steps