Installing MXNet on Ubuntu

The following installation instructions are for installing MXNet on computers running Ubuntu 16.04. Support for later versions of Ubuntu is not yet available.

Contents

CUDA Dependencies

If you plan to build with GPU, you need to set up the environment for CUDA and cuDNN.

First, download and install CUDA toolkit. CUDA 9.2 is recommended.

Then download cuDNN 7.1.4.

Unzip the file and change to the cuDNN root directory. Move the header and libraries to your local CUDA Toolkit folder:

    tar xvzf cudnn-9.2-linux-x64-v7.1
    sudo cp -P cuda/include/cudnn.h /usr/local/cuda/include
    sudo cp -P cuda/lib64/libcudnn* /usr/local/cuda/lib64
    sudo chmod a+r /usr/local/cuda/include/cudnn.h /usr/local/cuda/lib64/libcudnn*
    sudo ldconfig

Quick Installation

Install MXNet for Python

Dependencies

The following scripts will install Ubuntu 16.04 dependencies for MXNet Python development.

wget https://raw.githubusercontent.com/apache/incubator-mxnet/master/ci/docker/install/ubuntu_core.sh
wget https://raw.githubusercontent.com/apache/incubator-mxnet/master/ci/docker/install/ubuntu_python.sh
sudo ./ubuntu_core.sh
sudo ./ubuntu_python.sh

Using the latest MXNet with CUDA 9.2 package is recommended for the fastest training speeds with MXNet.

Recommended for training: bash pip install mxnet-cu92

Recommended for inference: bash pip install mxnet-cu92mkl

Alternatively, you can use the table below to select the package that suits your purpose.

MXNet Version Basic CUDA MKL-DNN CUDA/MKL-DNN
Latest mxnet mxnet-cu92 mxnet-mkl mxnet-cu92mkl

pip Package Availability

The following table presents the pip packages that are recommended for each version of MXNet.

pip package table

To install an older version of MXNet with one of the packages in the previous table add == with the version you require. For example for version 1.1.0 of MXNet with CUDA 8, you would use pip install mxnet-cu80==1.1.0.

Build MXNet from Source

You can build MXNet from source, and then you have the option of installing language-specific bindings, such as Scala, Java, Julia, R or Perl. This is a two-step process:

  1. Build the shared library from the MXNet C++ source code.
  2. (optional) Install the supported language-specific packages for MXNet. Be sure to check that section first, as some scripts may be available to handle all of the dependencies, MXNet build, and language bindings for you. Here they are again for quick access:

Note: To change the compilation options for your build, edit the make/config.mk file prior to building MXNet. More information on this is mentioned in the different language package instructions.

Build the Shared Library

Quick MXNet Build

You can quickly build MXNet from source with the following script found in the /docs/install folder:

cd docs/install
./install_mxnet_ubuntu_python.sh

Or you can go through a manual process described next.

Manual MXNet Installation

It is recommended that you review the general build from source instructions before continuing.

On Ubuntu versions 16.04 or later, you need the following dependencies:

Step 1: Install prerequisite packages. bash sudo apt-get update sudo apt-get install -y build-essential git ninja-build ccache

For Ubuntu 18.04 and CUDA builds you need to update CMake

#!/usr/bin/env bash
set -exuo pipefail
sudo apt remove --purge --auto-remove cmake

# Update CMAKE for correct cuda autotedetection: https://github.com/clab/dynet/issues/1457
version=3.14
build=0
mkdir -p ~/tmp
cd ~/tmp
wget https://cmake.org/files/v$version/cmake-$version.$build.tar.gz
tar -xzvf cmake-$version.$build.tar.gz
cd cmake-$version.$build/
./bootstrap
make -j$(nproc)
sudo make install

Step 2: Install a Math Library.

Details on the different math libraries are found in the build from source guide's Math Library Selection section.

For OpenBLAS use:

    sudo apt-get install -y libopenblas-dev

For other libraries, visit the Math Library Selection section.

Step 3: Install OpenCV.

MXNet uses OpenCV for efficient image loading and augmentation operations.

    sudo apt-get install -y libopencv-dev

Step 4: Download MXNet sources and build MXNet core shared library.

If building on CPU and using OpenBLAS:

Clone the repository:

    git clone --recursive https://github.com/apache/incubator-mxnet.git
    cd incubator-mxnet

Build with CMake and ninja, without GPU and without MKL.

    rm -rf build
    mkdir -p build && cd build
    cmake -GNinja \
        -DUSE_CUDA=OFF \
        -DUSE_MKL_IF_AVAILABLE=OFF \
        -DCMAKE_CUDA_COMPILER_LAUNCHER=ccache \
        -DCMAKE_C_COMPILER_LAUNCHER=ccache \
        -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
        -DCMAKE_BUILD_TYPE=Release \
    ..
    ninja

If building on CPU and using MKL and MKL-DNN (make sure MKL is installed according to Math Library Selection and MKL-DNN README):

    rm -rf build
    mkdir -p build && cd build
    cmake -GNinja \
        -DUSE_CUDA=OFF \
        -DUSE_MKL_IF_AVAILABLE=ON \
        -DCMAKE_CUDA_COMPILER_LAUNCHER=ccache \
        -DCMAKE_C_COMPILER_LAUNCHER=ccache \
        -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
        -DCMAKE_BUILD_TYPE=Release \
    ..
    ninja

If building on GPU (make sure you have installed the CUDA dependencies first): Cuda 10.1 in Ubuntu 18.04 builds fine but is not currently tested in CI.

    rm -rf build
    mkdir -p build && cd build
    cmake -GNinja \
        -DUSE_CUDA=ON \
        -DUSE_MKL_IF_AVAILABLE=OFF \
        -DCMAKE_CUDA_COMPILER_LAUNCHER=ccache \
        -DCMAKE_C_COMPILER_LAUNCHER=ccache \
        -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
        -DCMAKE_BUILD_TYPE=Release \
    ..
    ninja

Note - You can explore and use more compilation options as they are delcared in the top of CMakeLists.txt and also review common usage examples. Optionally, you can also use a higher level, scripted version of the above with an editable CMake options file by doing the following:

cp cmake/cmake_options.yml .
# Edit cmake_options.yml in the MXNet root to your taste
$EDITOR cmake_options.yml
# Launch a local CMake build
./dev_menu.py build

Building from source creates a library called libmxnet.so in the build folder in your MXNet project root.

After building the MXNet library, you may install language bindings.

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:

$ cd python
$ pip install -e .

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.

Optional Python Packages

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.

sudo pip install graphviz==0.8.4 \
                 jupyter

Install the MXNet Package for C++

Refer to the C++ Package setup guide.

Install the MXNet Package for Clojure

Refer to the Clojure setup guide.

Install the MXNet Package for Julia

Install Julia

The package available through apt-get is old and not compatible with the latest version of MXNet. Fetch the latest version (1.0.3 at the time of this writing).

wget -qO julia-10.tar.gz https://julialang-s3.julialang.org/bin/linux/x64/1.0/julia-1.0.3-linux-x86_64.tar.gz

Place the extracted files somewhere like a julia folder in your home dir.

mkdir ~/julia
mv julia-10.tar.gz ~/julia
cd ~/julia
tar xvf julia-10.tar.gz

Test Julia. bash cd julia-1.0.3/bin julia -e 'using InteractiveUtils; versioninfo()'

If you're still getting the old version, remove it. bash sudo apt remove julia

Update your PATH to have Julia's new location. Add this to your .zshrc, .bashrc, .profile or .bash_profile. bash export PATH=~/julia/julia-1.0.3/bin:$PATH

Validate your PATH. bash echo $PATH

Validate Julia works and is the expected version. bash julia -e 'using InteractiveUtils; versioninfo()'

Setup Your MXNet-Julia Environment

For each of the following environment variables, add the commands to your .zshrc, .bashrc, .profile or .bash_profile to make them persist.

Create a julia-depot folder and environment variable. bash mkdir julia-depot export JULIA_DEPOT_PATH=$HOME/julia/julia-depot

To use the Julia binding with an existing libmxnet installation, set the MXNET_HOME environment variable to the MXNet source root. For example: bash export MXNET_HOME=$HOME/incubator-mxnet

Now set the LD_LIBRARY_PATH environment variable to where libmxnet.so is found. If you can't find it, you might have skipped the building MXNet step. Go back and build MXNet first. For example: bash export LD_LIBRARY_PATH=$HOME/incubator-mxnet/lib:$LD_LIBRARY_PATH

Verify the location of libjemalloc.so and set the LD_PRELOAD environment variable. bash export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so:$LD_PRELOAD

With all of these updates, here's an example of what you might want to have in your .zshrc, .bashrc, .profile or .bash_profile.

export PATH=$HOME/bin:$HOME/.local/bin:$HOME/julia/julia-1.0.3/bin:$PATH
export JULIA_DEPOT_PATH=$HOME/julia/julia-depot
export MXNET_HOME=$HOME/incubator-mxnet
export LD_LIBRARY_PATH=$HOME/incubator-mxnet/lib:$LD_LIBRARY_PATH
export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so:$LD_PRELOAD

Install MXNet with Julia:

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

For more details about installing and using MXNet with Julia, see the MXNet Julia documentation.

Install the MXNet Package for Perl

Before you build MXNet for Perl from source code, you must complete building the shared library. After you build the shared library, run the following command from the MXNet source root directory to build the MXNet Perl package:

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

    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

Install the MXNet Package for R

Building MXNet from source is a 2 step process. 1. Build the MXNet core shared library, libmxnet.so, from source. 2. Build the R bindings.

Quick MXNet-R Installation

You can quickly build MXNet-R with the following two scripts found in the /docs/install folder:

git clone --recursive https://github.com/apache/incubator-mxnet.git mxnet
cd mxnet/docs/install
./install_mxnet_ubuntu_python.sh
./install_mxnet_ubuntu_r.sh

Or you can go through a manual process described next.

Manual MXNet-R Installation

Minimum Requirements 1. GCC 4.8 or later to compile C++ 11. 2. GNU Make


Build the MXNet core shared library

Step 1 Install build tools and git. bash $ sudo apt-get update $ sudo apt-get install -y build-essential git

Step 2 Install OpenBLAS.

MXNet uses BLAS and LAPACK libraries for accelerated numerical computations on CPU machine. There are several flavors of BLAS/LAPACK libraries - OpenBLAS, ATLAS and MKL. In this step we install OpenBLAS. You can choose to install ATLAS or MKL. bash $ sudo apt-get install -y libopenblas-dev liblapack-dev

Step 3 Install OpenCV.

MXNet uses OpenCV for efficient image loading and augmentation operations. bash $ sudo apt-get install -y libopencv-dev

Step 4 Download MXNet sources and build MXNet core shared library. You can clone the repository as described in the following code block, or you may try the download links for your desired MXNet version.

$ git clone --recursive https://github.com/apache/incubator-mxnet
$ cd incubator-mxnet
$ echo "USE_OPENCV = 1" >> ./config.mk
$ echo "USE_BLAS = openblas" >> ./config.mk
$ make -j $(nproc)

Note - USE_OPENCV and USE_BLAS are make file flags to set compilation options to use OpenCV and BLAS library. You can explore and use more compilation options in make/config.mk.


Step 5 Make and install the MXNet-R bindings.

$ make rpkg

Verify MXNet-R Installation

You can verify your MXNet-R installation as follows:

sudo -i R

At the R prompt enter the following:

library(mxnet)
a <- mx.nd.ones(c(2,3), ctx = mx.cpu())
b <- a * 2 + 1
b

You should see the following output:

     [,1] [,2] [,3]
[1,]    3    3    3
[2,]    3    3    3
> quit()

Install the MXNet Package for Scala

To use the MXNet-Scala package, you can acquire the Maven package as a dependency.

Further information is in the MXNet-Scala Setup Instructions.

If you use IntelliJ or a similar IDE, you may want to follow the MXNet-Scala on IntelliJ tutorial instead.

Install the MXNet Package for Java

To use the MXNet-Java package, you can acquire the Maven package as a dependency.

Further information is in the MXNet-Java Setup Instructions.

If you use IntelliJ or a similar IDE, you may want to follow the MXNet-Java on IntelliJ tutorial instead.

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