Build MXNet from Source
Building and installing MXNet from source is a three-step process. First, build
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.
- Obtaining the source
- Installing MXNet’s recommended dependencies
- Overview of optional dependencies and optional features
- Building MXNet
- 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 (incubating) 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
git clone --recursive https://github.com/apache/incubator-mxnet 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.
Installing MXNet’s recommended dependencies
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, …)
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
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.
# 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 install llvm
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
lib directories for
example by typing
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
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
tests/python/gpu/test_nccl.py. In MXNet 1.x it is run via
To get the best performance out of NCCL it is recommended to set environment
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
MXNet 1.x can be built either with a classic Makefile setup or with the
cross platform build system. Starting with MXNet 1.7, MXNet recommends using the
cmake cross platform build tool.
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
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
Please see the
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
file on how to configure and compile MXNet. This method is supported on all 1.x
To enable the optional MXNet C++ package, please set the
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:
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
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.
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.