Installing MXNet on Windows

The following describes how to install with pip for computers with CPUs, Intel CPUs, and NVIDIA GPUs. Further along in the document you can learn how to build MXNet from source on Windows, or how to install packages that support different language APIs to MXNet.

Prerequisites

Minimum System Requirements

  • Windows 71, 10, Server 2012 R2, or Server 2016
  • Visual Studio 2015 or 2017 (any type)
  • Python 2.7 or 3.6
  • pip

1. There are known issues with Windows 7.

Install MXNet with Python

The easiest way to install MXNet on Windows is by using a Python pip package.

Note: Windows pip packages typically release a few days after a new version MXNet is released. Make sure you verify which version gets installed.

Install with CPUs

Install MXNet with CPU support with Python:

pip install mxnet

Now validate your MXNet installation with Python.

Install with Intel CPUs

MXNet has experimental support for Intel MKL and MKL-DNN. When using supported Intel hardware, inference and training can be vastly faster when using MXNet with MKL or MKL-DNN.

The following steps will setup MXNet with MKL. MKL-DNN can be enabled only when building from source.

  1. Download and install Intel MKL (registration required).
  2. Install MXNet with MKL support with Python:
pip install mxnet-mkl

Now validate your MXNet installation with Python.

Install with NVIDIA GPUs

When using supported NVIDIA GPU hardware, inference and training can be vastly faster with NVIDIA CUDA and cuDNN. You have two options for installing MXNet with CUDA support with a Python package.

Install with CUDA Support

The following steps will setup MXNet with CUDA. cuDNN can be enabled only when building from source.

  1. Install Microsoft Visual Studio 2017 or Microsoft Visual Studio 2015.
  2. Download and install NVIDIA CUDA. CUDA versions 9.2 or 9.0 are recommended. Some issues with CUDA 9.1 have been identified in the past.
  3. Download and install NVIDIA_CUDA_DNN
  4. Install MXNet with CUDA support with pip:
pip install mxnet-cu92

Once you have installed a version of MXNet, validate your MXNet installation with Python.

Install with CUDA and MKL Support

You can also use a combination of CPU/GPU enhancements provided by Intel and NVIDIA.

The following steps will setup MXNet with CUDA and MKL.

  1. Install Microsoft Visual Studio 2017 or Microsoft Visual Studio 2015.
  2. Download and install Intel MKL (registration required).
  3. Download and install NVIDIA CUDA.
  4. Download and install NVIDIA_CUDA_DNN
  5. Install MXNet with MKL support with pip:
pip install mxnet-cu92mkl

Once you have installed a version of MXNet, validate your MXNet installation with Python.

Notes on the Python Packages

To get further enhancements for deep neural networks, you may want to enable MKL-DNN and/or cuDNN. Each of these require you to build from source and to enable the build flags for each.

Check the chart below for other options or refer to PyPI for other MXNet pip packages.

pip packages

Build from Source

IMPORTANT: It is recommended that you review the build from source guide first. It describes many of the build options that come with MXNet in more detail. You may decide to install additional dependencies and modify your build flags after reviewing this material.

We provide two primary options to build and install MXNet yourself using Microsoft Visual Studio 2017 or Microsoft Visual Studio 2015.

NOTE: Visual Studio 2017’s compiler is vc15. This is not to be confused with Visual Studio 2015’s compiler, vc14.

You also have the option to install MXNet with MKL or MKL-DNN. In this case it is recommended that you refer to the MKLDNN_README.

Option 1: Build with Microsoft Visual Studio 2017 (VS2017)

To build and install MXNet yourself using VS2017, you need the following dependencies. You may try a newer version of a particular dependency, but please open a pull request or issue to update this guide if a newer version is validated.

  1. Install or update VS2017.
    • If VS2017 is not already installed, download and install it. You can download and install the free community edition.
    • When prompted about installing Git, go ahead and install it.
    • If VS2017 is already installed you will want to update it. Proceed to the next step to modify your installation. You will be given the opportunity to update VS2017 as well
  2. Follow the instructions for opening the Visual Studio Installer to modify Individual components.
  3. Once in the Visual Studio Installer application, update as needed, then look for and check VC++ 2017 version 15.4 v14.11 toolset, and click Modify.
  4. Change the version of the Visual studio 2017 to v14.11 using the following command (by default the VS2017 is installed in the following path):
"C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat" -vcvars_ver=14.11
  1. Download and install CMake if it is not already installed. CMake v3.12.2 has been tested with MXNet.
  2. Download and run the OpenCV package. There are more recent versions of OpenCV, so please create an issue/PR to update this info if you validate one of these later versions.
  3. This will unzip several files. You can place them in another directory if you wish. We will use C:\utils(mkdir C:\utils) as our default path.
  4. Set the environment variable OpenCV_DIR to point to the OpenCV build directory that you just unzipped. Start cmd and type set OpenCV_DIR=C:\utils\opencv\build.
  5. If you don’t have the Intel Math Kernel Library (MKL) installed, you can install it and follow the MKLDNN_README from here, or you can use OpenBLAS. These instructions will assume you’re using OpenBLAS.
  6. Download the OpenBlas package. Later versions of OpenBLAS are available, but you would need to build from source. v0.2.19 is the most recent version that ships with binaries. Contributions of more recent binaries would be appreciated.
  7. Unzip the file, rename it to OpenBLAS and put it under C:\utils. You can place the unzipped files and folders in another directory if you wish.
  8. Set the environment variable OpenBLAS_HOME to point to the OpenBLAS directory that contains the include and lib directories and type set OpenBLAS_HOME=C:\utils\OpenBLAS on the command prompt(cmd).
  9. Download and install CUDA. If you already had CUDA, then installed VS2017, you should reinstall CUDA now so that you get the CUDA toolkit components for VS2017 integration. Note that the latest CUDA version supported by MXNet is 9.2. You might also want to find other CUDA verion on the Legacy Releases.
  10. Download and install cuDNN. To get access to the download link, register as an NVIDIA community user. Then follow the link to install the cuDNN and put those libraries into C:\cuda.
  11. Download and install git if you haven’t already.

After you have installed all of the required dependencies, build the MXNet source code:

  1. Start cmd in windows.
  2. Download the MXNet source code from GitHub by using following command:
cd C:\
git clone https://github.com/apache/incubator-mxnet.git --recursive
  1. Verify that the DCUDNN_INCLUDE and DCUDNN_LIBRARY environment variables are pointing to the include folder and cudnn.lib file of your CUDA installed location, and C:\incubator-mxnet is the location of the source code you just cloned in the previous step.
  2. Create a build dir using the following command and go to the directory, for example:
mkdir C:\incubator-mxnet\build
cd C:\incubator-mxnet\build
  1. Compile the MXNet source code with cmake by using following command:
cmake -G "Visual Studio 15 2017 Win64" -T cuda=9.2,host=x64 -DUSE_CUDA=1 -DUSE_CUDNN=1 -DUSE_NVRTC=1 -DUSE_OPENCV=1 -DUSE_OPENMP=1 -DUSE_BLAS=open -DUSE_LAPACK=1 -DUSE_DIST_KVSTORE=0 -DCUDA_ARCH_LIST=Common -DCUDA_TOOLSET=9.2 -DCUDNN_INCLUDE=C:\cuda\include -DCUDNN_LIBRARY=C:\cuda\lib\x64\cudnn.lib "C:\incubator-mxnet"
  • Make sure you set the environment variables correctly (OpenBLAS_HOME, OpenCV_DIR) and change the version of the Visual studio 2017 to v14.11 before enter above command.
  1. After the CMake successfully completed, compile the the MXNet source code by using following command:
msbuild mxnet.sln /p:Configuration=Release;Platform=x64 /maxcpucount

Option 2: Build with Visual Studio 2015

To build and install MXNet yourself using Microsoft Visual Studio 2015, you need the following dependencies. You may try a newer version of a particular dependency, but please open a pull request or issue to update this guide if a newer version is validated.

  1. If Microsoft Visual Studio 2015 is not already installed, download and install it. You can download and install the free community edition. At least Update 3 of Microsoft Visual Studio 2015 is required to build MXNet from source. Upgrade via it’s Tools -> Extensions and Updates... | Product Updates menu.
  2. Download and install CMake if it is not already installed.
  3. Download and install OpenCV.
  4. Unzip the OpenCV package.
  5. Set the environment variable OpenCV_DIR to point to the OpenCV build directory (C:\opencv\build\x64\vc14 for example). Also, you need to add the OpenCV bin directory (C:\opencv\build\x64\vc14\bin for example) to the PATH variable.
  6. If you don’t have the Intel Math Kernel Library (MKL) installed, download and install OpenBlas.
  7. Set the environment variable OpenBLAS_HOME to point to the OpenBLAS directory that contains the include and lib directories. Typically, you can find the directory in C:\Program files (x86)\OpenBLAS\.
  8. Download and install CUDA and cuDNN. To get access to the download link, register as an NVIDIA community user.
  9. Set the environment variable CUDACXX to point to the CUDA Compiler(C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v9.1\bin\nvcc.exe for example).
  10. Set the environment variable CUDNN_ROOT to point to the cuDNN directory that contains the include, lib and bin directories (C:\Downloads\cudnn-9.1-windows7-x64-v7\cuda for example).

After you have installed all of the required dependencies, build the MXNet source code:

  1. Download the MXNet source code from GitHub (make sure you also download third parties submodules e.g. git clone --recurse-submodules).
  2. Use CMake to create a Visual Studio solution in ./build.
  3. In Visual Studio, open the solution file,.sln, and compile it. These commands produce a library called mxnet.dll in the ./build/Release/ or ./build/Debug folder.

Next, we install graphviz library that we use for visualizing network graphs you build on MXNet. We will also install Jupyter Notebook used for running MXNet tutorials and examples.

  • Install graphviz by downloading MSI installer from Graphviz Download Page. Note Make sure to add graphviz executable path to PATH environment variable. Refer here for more details
  • Install Jupyter by installing Anaconda for Python 2.7 Note Do not install Anaconda for Python 3.5. MXNet has a few compatibility issues with Python 3.5.

We have installed MXNet core library. Next, we will install MXNet interface package for programming language of your choice:

Install the MXNet Package for Python

These steps are required after building from source. If you already installed MXNet by using pip, you do not need to do these steps to use MXNet with Python.

  1. Install Python using windows installer available here.
  2. Install Numpy using windows installer available here.
  3. Start cmd and create a folder named common(mkdir C:\common)
  4. Download the mingw64_dll.zip, unzip and copy three libraries (.dll files) that openblas.dll depends on to C:\common.
  5. Copy the required .dll file to C:\common and make sure following libraries (.dll files) in the folder.
libgcc_s_seh-1.dll (in mingw64_dll)
libgfortran-3.dll (in mingw64_dll)
libquadmath-0.dll (in mingw64_dll)
libopenblas.dll (in OpenBlas folder you download)
opencv_world341.dll (in OpenCV folder you download)
  1. Add C:\common to Environment Variables.
  • Type control sysdm.cpl on cmp
  • Select the Advanced tab and click Environment Variables
  • Double click the Path and click New
  • Add C:\common and click OK
  1. Use setup.py to install the package.
    # Assuming you are in root mxnet source code folder
    cd python
    python setup.py install

Done! We have installed MXNet with Python interface.

You can continue with using MXNet-Python, or if you want to try a different language API for MXNet, keep reading. Otherwise, jump ahead to next steps.

Install the MXNet Package for R

MXNet for R is available for both CPUs and GPUs.

Installing MXNet-R on a Computer with a CPU Processor

To install MXNet on a computer with a CPU processor, choose from two options:

  • Use the prebuilt binary package
  • Build the library from source code

Installing MXNet-R with the Prebuilt Binary Package(CPU)

For Windows users, MXNet provides prebuilt binary packages. You can install the package directly in the R console.

For CPU-only package:

  cran <- getOption("repos")
  cran["dmlc"] <- "https://apache-mxnet.s3-accelerate.dualstack.amazonaws.com/R/CRAN/"
  options(repos = cran)
  install.packages("mxnet")

Building MXNet-R from Source Code(CPU)

  1. Clone the MXNet github repo.
git clone --recursive https://github.com/apache/incubator-mxnet

The --recursive is to clone all the submodules used by MXNet. You will be editing the "/mxnet/R-package" folder.

  1. Download prebuilt GPU-enabled MXNet libraries for Windows from Windows release. You will need mxnet_x64_vc14_cpu.7z and prebuildbase_win10_x64_vc14.7z where X stands for your CUDA toolkit version
  2. Create a folder called R-package/inst/libs/x64. MXNet supports only 64-bit operating systems, so you need the x64 folder.
  3. Copy the following shared libraries (.dll files) into the R-package/inst/libs/x64 folder:
libgcc_s_seh-1.dll
libgfortran-3.dll
libmxnet.dll
libmxnet.lib
libopenblas.dll
libquadmath-0.dll
mxnet.dll
unzip.exe
unzip32.dll
vcomp140.dll
wget.exe

These dlls can be found in prebuildbase_win10_x64_vc14/3rdparty, mxnet_x64_vc14_cpu/build, mxnet_x64_vc14_cpu/lib.

  1. Copy the header files from dmlc, mxnet, mxshadow and nnvm from mxnet_x64_vc14_cpu/include and mxnet_x64_vc14_cpu/nvnm/include into ./R-package/inst/include. It should look like:
./R-package/inst
└── include
    ├── dmlc
    ├── mxnet
    ├── mshadow
    └── nnvm
  1. Make sure that R executable is added to your PATH in the environment variables. Running the where R command at the command prompt should return the location.
  2. Also make sure that Rtools is installed and the executable is added to your PATH in the environment variables.
  3. Temporary patch - im2rec currently results in crashes during the build. Remove the im2rec.h and im2rec.cc files in R-package/src/ from cloned repository and comment out the two im2rec lines in R-package/src/mxnet.cc as shown below.
#include "./kvstore.h"
#include "./export.h"
//#include "./im2rec.h"
......
......
  DataIterCreateFunction::InitRcppModule();
  KVStore::InitRcppModule();
  Exporter::InitRcppModule();
//  IM2REC::InitRcppModule();
}
  1. Now open the Windows CMD with admin rights and change the directory to the mxnet folder(cloned repository). Then use the following commands to build R package:
echo import(Rcpp) > R-package\NAMESPACE
echo import(methods) >> R-package\NAMESPACE
Rscript -e "install.packages('devtools', repos = 'https://cloud.r-project.org')"
cd R-package
Rscript -e "library(devtools); library(methods); options(repos=c(CRAN='https://cloud.r-project.org')); install_deps(dependencies = TRUE)"
cd ..

R CMD INSTALL --no-multiarch R-package

Rscript -e "require(mxnet); mxnet:::mxnet.export('R-package')"
rm R-package/NAMESPACE
Rscript -e "require(devtools); install_version('roxygen2', version = '5.0.1', repos = 'https://cloud.r-project.org/', quiet = TRUE)"
Rscript -e "require(roxygen2); roxygen2::roxygenise('R-package')"

R CMD INSTALL --build --no-multiarch R-package

Installing MXNet-R on a Computer with a GPU Processor

To install MXNet on a computer with a GPU processor, choose from two options:

  • Use the prebuilt binary package
  • Build the library from source code

However, a few dependencies remain for both options. You will need the following:

  • Install Nvidia-drivers if not installed. Latest driver based on your system configuration is recommended.
  • Install Microsoft Visual Studio (VS2015 or VS2017 is required by CUDA)
  • Install NVidia CUDA Toolkit(cu92 is recommended though we support cu80, cu90, cu91 and cu92)
  • Download and install CuDNN (to provide a Deep Neural Network library). Latest version recommended.

Note: A pre-requisite to above softwares is Nvidia-drivers which we assume is installed.

Installing MXNet-R with the Prebuilt Binary Package(GPU)

For Windows users, MXNet provides prebuilt binary packages. You can install the package directly in the R console after you have the above software installed.

For GPU package:

  cran <- getOption("repos")
  cran["dmlc"] <- "https://apache-mxnet.s3-accelerate.dualstack.amazonaws.com/R/CRAN/GPU/cu92"
  options(repos = cran)
  install.packages("mxnet")

Change cu92 to cu80, cu90 or cu91 based on your CUDA toolkit version. Currently, MXNet supports these versions of CUDA.

Building MXNet-R from Source Code(GPU)

After you have installed above software, continue with the following steps to build MXNet-R:

  1. Clone the MXNet github repo.
git clone --recursive https://github.com/apache/incubator-mxnet

The --recursive is to clone all the submodules used by MXNet. You will be editing the "/mxnet/R-package" folder.

  1. Download prebuilt GPU-enabled MXNet libraries for Windows from https://github.com/yajiedesign/mxnet/releases. You will need mxnet_x64_vc14_gpu_cuX.7z and prebuildbase_win10_x64_vc14.7z where X stands for your CUDA toolkit version
  2. Create a folder called R-package/inst/libs/x64. MXNet supports only 64-bit operating systems, so you need the x64 folder.
  3. Copy the following shared libraries (.dll files) into the R-package/inst/libs/x64 folder:
libgcc_s_seh-1.dll
libgfortran-3.dll
libmxnet.dll
libmxnet.lib
libopenblas.dll
libquadmath-0.dll
mxnet.dll
unzip.exe
unzip32.dll
vcomp140.dll
wget.exe

These dlls can be found in prebuildbase_win10_x64_vc14/3rdparty, mxnet_x64_vc14_gpu_cuX/build, mxnet_x64_vc14_gpu_cuX/lib.

  1. Copy the header files from dmlc, mxnet, mxshadow and nnvm from mxnet_x64_vc14_gpuX/include and mxnet_x64_vc14_gpuX/nvnm/include into ./R-package/inst/include. It should look like:
./R-package/inst
└── include
    ├── dmlc
    ├── mxnet
    ├── mshadow
    └── nnvm
  1. Make sure that R executable is added to your PATH in the environment variables. Running the where R command at the command prompt should return the location.
  2. Also make sure that Rtools is installed and the executable is added to your PATH in the environment variables.
  3. Temporary patch - im2rec currently results in crashes during the build. Remove the im2rec.h and im2rec.cc files in R-package/src/ from cloned repository and comment out the two im2rec lines in R-package/src/mxnet.cc as shown below.
#include "./kvstore.h"
#include "./export.h"
//#include "./im2rec.h"
......
......
  DataIterCreateFunction::InitRcppModule();
  KVStore::InitRcppModule();
  Exporter::InitRcppModule();
//  IM2REC::InitRcppModule();
}
  1. Now open the Windows CMD with admin rights and change the directory to the mxnet folder(cloned repository). Then use the following commands to build R package:
echo import(Rcpp) > R-package\NAMESPACE
echo import(methods) >> R-package\NAMESPACE
Rscript -e "install.packages('devtools', repos = 'https://cloud.r-project.org')"
cd R-package
Rscript -e "library(devtools); library(methods); options(repos=c(CRAN='https://cloud.r-project.org')); install_deps(dependencies = TRUE)"
cd ..

R CMD INSTALL --no-multiarch R-package

Rscript -e "require(mxnet); mxnet:::mxnet.export('R-package')"
rm R-package/NAMESPACE
Rscript -e "require(devtools); install_version('roxygen2', version = '5.0.1', repos = 'https://cloud.r-project.org/', quiet = TRUE)"
Rscript -e "require(roxygen2); roxygen2::roxygenise('R-package')"

R CMD INSTALL --build --no-multiarch R-package

Note: To maximize its portability, the MXNet library is built with the Rcpp end. Computers running Windows need MSVC (Microsoft Visual C++) to handle CUDA toolchain compatibilities.

Install the MXNet Package for Julia

The MXNet package for Julia is hosted in a separate repository, MXNet.jl, which is available on GitHub. To use Julia binding it with an existing libmxnet installation, set the MXNET_HOME environment variable by running the following command:

export MXNET_HOME=/<path to>/libmxnet

The path to the existing libmxnet installation should be the root directory of libmxnet. In other words, you should be able to find the libmxnet.so file at $MXNET_HOME/lib. For example, if the root directory of libmxnet is ~, you would run the following command:

    export MXNET_HOME=/~/libmxnet

You might want to add this command to your ~/.bashrc file. If you do, you can install the Julia package in the Julia console using the following command:

    Pkg.add("MXNet")

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

Installing the MXNet Package for Scala

MXNet-Scala is not yet available for Windows.