You can run MXNet on Amazon Linux, Ubuntu/Debian, OS X, and Windows operating systems. MXNet can also be run on Docker and on Cloud like AWS. MXNet currently supports Python, R, Julia, and Scala programming languages.

Step by step instructions for setting up MXNet:

This topic also covers the following:

If you encounter problems with the set up instructions and don’t find a solution in Common installation problems, ask questions at mxnet/issues. If you can fix the problem, send a pull request. For details, see contribution guidelines.


This section lists the basic requirements for running MXNet, requirements for using it with GPUs, and requirements to support computer vision and image augmentation.

Note: Setting up all basic(CPU only) required dependencies is covered as part of individual OS installation guide. This section is provided for power users who wants to set up alternate dependencies(GPU/Intel MKL etc..) and experiment.

Minimum Requirements

You must have the following:

  • A C++ compiler that supports C++ 11. The C++ compiler compiles and builds MXNet source code. Supported compilers include the following:

  • G++ (4.8 or later)

  • Clang

  • A BLAS (Basic Linear Algebra Subprograms) library. BLAS libraries contain routines that provide the standard building blocks for performing basic vector and matrix operations. You need a BLAS library to perform basic linear algebraic operations. Supported BLAS libraries include the following:

  • Graphviz for visualizing the network graphs.

  • Jupyter Notebook for running examples and tutorials of MXNet.

Requirements for Using GPUs

  • A GPU with support for Compute Capability 2.0 or higher. Compute capability describes which features are supported by CUDA hardware. For a list of features supported by each compute capability, see CUDA Version features and specifications. For a list of features supported by NVIDIA GPUs, see CUDA GPUs.
  • The CUDA Toolkit 7.0 or higher. The CUDA Toolkit is an environment that allows MXNet to run on NVIDIA GPUs. It includes a compiler, math libraries, and debugging tools. To download the latest version, see CUDA Toolkit download page.
  • The CuDNN (CUDA Deep Neural Network) library. The CuDNN library accelerates GPU computation by providing low-level GPU performance tuning. To download the latest version, see CUDA Deep Neural Network.

Requirements for Computer Vision and Image Augmentation Support

If you need to support computer vision and image augmentation, you need OpenCV. The Open Source Computer Vision (OpenCV) library contains programming functions for computer vision and image augmentation. For more information, see OpenCV.

Build the Dependent Libraries from Source Code

This section provides instructions on how to build MXNet’s dependent libraries from source code. This approach is useful in two specific situations:

  • If you are using an earlier version of Linux on your server and required packages are either missing or Yum or apt-get didn’t install a later version of the packages.
  • If you do not have root permission to install packages. In this case, you need to change the installation directory from /usr/local to one where you do have permission. The following examples use the directory ${HOME}.

Building GCC from Source Code

To build the GNU Complier Collection (GCC) from source code, you need the 32-bit libc library.

  1. Install libc with one of the following system-specific commands:

        sudo apt-get install libc6-dev-i386 # In Ubuntu
        sudo yum install glibc-devel.i686   # In RHEL (Red Hat Linux)
        sudo yum install glibc-devel.i386   # In CentOS 5.8
        sudo yum install glibc-devel.i686   # In CentOS 6/7
  2. To download and extract the GCC source code, run the following commands:

        wget http://mirrors.concertpass.com/gcc/releases/gcc-4.8.5/gcc-4.8.5.tar.gz
        tar -zxf gcc-4.8.5.tar.gz
        cd gcc-4.8.5
  3. To build GCC, run the following commands:

        mkdir release && cd release
        ../configure --prefix=/usr/local --enable-languages=c,c++
        make -j10
        sudo make install
  4. Add the lib path to your ~/.bashrc file:

        export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/lib64

Build OpenCV from Source Code

To build OpenCV from source code, you need the cmake library .

  • If you don’t have cmake or if your version of cmake is earlier than 3.6.1 (such as the default version of cmake on RHEL), run the following commands to install a newer version of cmake:

        wget https://cmake.org/files/v3.6/cmake-3.6.1-Linux-x86_64.tar.gz
        tar -zxvf cmake-3.6.1-Linux-x86_64.tar.gz
        alias cmake="cmake-3.6.1-Linux-x86_64/bin/cmake"
  • To download and extract the OpenCV source code, run the following commands:

        wget https://codeload.github.com/opencv/opencv/zip/2.4.13
        unzip 2.4.13
        cd opencv-2.4.13
        mkdir release
        cd release/
  • Build OpenCV. The following commands build OpenCV without GPU support, which might significantly slow down an MXNet program running on a GPU processor. It also disables 1394 which might generate a warning:

        make -j8
        sudo make install
  • Add the lib path to your ~/.bashrc file:

        export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig/

Common Installation Problems

This section provides solutions for common installation problems.


Message: ImportError: No module named _graphviz

Cause: Graphviz is not installed.

Solution: On Mac, You can install Graphviz with below command

  brew install graphviz

Or, using pip

  brew install python
  pip install graphviz

Message: RuntimeError: failed to execute [‘dot’, ‘-Tsvg’], make sure the Graphviz executables are on your systems’ path

Cause: Graphviz executable (lib) path is currently not in the system path and program is unable to use Graphviz for plotting the graph

Solution: Add Graphviz executable (lib) path to your system path. On Mac/Linux machines, Graphviz is generally installed in - /usr/local/lib/graphviz/ or /usr/lib/graphviz/ or /usr/lib64/graphviz/ and on Windows - C:\Program Files (x86)\Graphviz2.38\bin.

Note If you are using Jupyter notebook, you may need to restart the kernel to refresh the system path and find Graphviz executable.

Mac OS X Error Message

Message: link error ld: library not found for -lgomp

Cause: The GNU implementation of OpenMP is not in the operating system’s library path.

Solution: Add the location of OpenMP to the library path:

  • Create the locate database by running the following command:

        sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.locate.plist
  • Locate the OpenMP library by running the following command:

        locate libgomp.dylib
  • To add OpenMP to your library path, replace path1 in the following command with the output from the last command:

        ln -s path1 /usr/local/lib/libgomp.dylib
  • To build your changes, run the following command:

        make -j$(sysctl -n hw.ncpu)

R Error Message

Message Unable to load mxnet after enabling CUDA

Solution: If you enabled CUDA when you installed MXNet, but can’t load mxnet, add the following lines to your $RHOME/etc/ldpaths environment variable:

export CUDA_HOME=/usr/local/cuda

Note: To find your $RHOME environment variable, use the R.home() command in R.