From d8c51e5fbe1e50a855bc84dacd6061533d6d6a3c Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Mon, 17 Sep 2018 16:59:43 -0700 Subject: [PATCH] replacing windows setup with newer instructions (#12504) * replacing windows setup with newer instructions * add pip instructions; clarify 2017 build * refinements * bump cmake version & note compiler option; add vs requirement for cuda, windows pip note --- docs/install/windows_setup.md | 246 ++++++++++++++++++++++++++-------- 1 file changed, 190 insertions(+), 56 deletions(-) diff --git a/docs/install/windows_setup.md b/docs/install/windows_setup.md index c974eeb858b0..01cd46658a7b 100755 --- a/docs/install/windows_setup.md +++ b/docs/install/windows_setup.md @@ -1,64 +1,203 @@ -# Installing MXNet in Windows +# Installing MXNet on Windows -On Windows, you can download and install the prebuilt MXNet package, or download, build, and install MXNet yourself. +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. -## Build the Shared Library -You can either use a prebuilt binary package or build from source to build the MXNet shared library - ```libmxnet.dll```. +- [Prerequisites](#prerequisites) +- [Install MXNet with Python](#install-mxnet-with-python) + - [Install with CPUs](#install-with-cpus) + - [Install with Intel CPUs](#install-with-intel-cpus) + - [Install with GPUs](#install-with-gpus) + - [Notes on the Python Packages](#notes-on-the-python-packages) +- [Build from Source](#build-from-source) +- Install MXNet with a Programming Language API + - [Python](#install-the-mxnet-package-for-python) + - [R](#install-mxnet-package-for-r) + - [Julia](#install-the-mxnet-package-for-julia) -### Installing the Prebuilt Package on Windows -MXNet provides a prebuilt package for Windows. The prebuilt package includes the MXNet library, all of the dependent third-party libraries, a sample C++ solution for Visual Studio, and the Python installation script. To install the prebuilt package: -1. Download the latest prebuilt package from the [Releases](https://github.com/dmlc/mxnet/releases) tab of MXNet. -2. Unpack the package into a folder, with an appropriate name, such as ```D:\MXNet```. -3. Open the folder, and install the package by double-clicking ```setupenv.cmd```. This sets up all of the environment variables required by MXNet. -4. Test the installation by opening the provided sample C++ Visual Studio solution and building it. +## Prerequisites +### Minimum System Requirements -  -This produces a library called ```libmxnet.dll```. +* Windows 71, 10, Server 2012 R2, or Server 2016 +* Visual Studio 2015 or 2017 (any type) +* Python 2.7 or 3.6 +* pip -### Building and Installing Packages on Windows +1. There are [known issues](https://github.com/apache/incubator-mxnet/issues?utf8=%E2%9C%93&q=is%3Aissue+windows7+label%3AWindows+) with Windows 7. ↩ -To build and install MXNet yourself, you need the following dependencies. Install the required dependencies: +### Recommended System Requirements -1. If [Microsoft Visual Studio 2015](https://www.visualstudio.com/vs/older-downloads/) is not already installed, download and install it. You can download and install the free community edition. -2. Download and Install [CMake](https://cmake.org/) if it is not already installed. -3. Download and install [OpenCV](http://sourceforge.net/projects/opencvlibrary/files/opencv-win/3.0.0/opencv-3.0.0.exe/download). -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 have Intel Math Kernel Library (MKL) installed, set ```MKL_ROOT``` to point to ```MKL``` directory that contains the ```include``` and ```lib```. Typically, you can find the directory in -```C:\Program Files (x86)\IntelSWTools\compilers_and_libraries_2018\windows\mkl```. -7. If you don't have the Intel Math Kernel Library (MKL) installed, download and install [OpenBlas](http://sourceforge.net/projects/openblas/files/v0.2.14/). -8. 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\```. -9. Download and install [CuDNN](https://developer.nvidia.com/cudnn). To get access to the download link, register as an NVIDIA community user. +* Windows 10, Server 2012 R2, or Server 2016 +* Visual Studio 2017 (any type) +* At least one [NVIDIA CUDA-enabled GPU](https://developer.nvidia.com/cuda-gpus) +* MKL-enabled CPU: Intel® Xeon® processor, Intel® Core™ processor family, Intel Atom® processor, or Intel® Xeon Phi™ processor +* Python 2.7 or 3.6 +* pip + + +## Install MXNet with Python + +The easiest way to install MXNet on Windows is by using a [Python pip package](https://pip.pypa.io/en/stable/installing/). + +**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: + +```bash +pip install mxnet +``` + +Now [validate your MXNet installation with Python](validate_mxnet.md). + +### Install with Intel CPUs + +MXNet has experimental support for Intel [MKL](https://software.intel.com/en-us/mkl) and [MKL-DNN](https://github.com/intel/mkl-dnn). When using supported Intel hardware, inference and training can be vastly faster when using MXNet with [MKL](https://software.intel.com/en-us/mkl) or [MKL-DNN](https://github.com/intel/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](https://software.intel.com/en-us/mkl/choose-download/windows) (registration required). +1. Install MXNet with MKL support with Python: + +```bash +pip install mxnet-mkl +``` + +Now [validate your MXNet installation with Python](validate_mxnet.md). + +### Install with NVIDIA GPUs + +When using supported NVIDIA GPU hardware, inference and training can be vastly faster with [NVIDIA CUDA](https://developer.nvidia.com/cuda-toolkit) and [cuDNN](https://developer.nvidia.com/cudnn). You have two options for installing MXNet with CUDA support with a Python package. +- [Install with CUDA support](#install-with-cuda-support) +- [Install with CUDA and MKL support](#install-with-cuda-and-mkl-support) + +#### 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](https://www.visualstudio.com/downloads/) or [Microsoft Visual Studio 2015](https://www.visualstudio.com/vs/older-downloads/). +1. Download and install [NVIDIA CUDA](https://developer.nvidia.com/cuda-downloads?target_os=Windows&target_arch=x86_64&target_version=10&target_type=exelocal). CUDA versions 9.2 or 9.0 are recommended. Some [issues with CUDA 9.1](https://github.com/apache/incubator-mxnet/labels/CUDA) have been identified in the past. +1. Install MXNet with CUDA support with pip: + +```bash +pip install mxnet-cu92 +``` + +Once you have installed a version of MXNet, [validate your MXNet installation with Python](validate_mxnet.md). + +#### 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](https://www.visualstudio.com/downloads/) or [Microsoft Visual Studio 2015](https://www.visualstudio.com/vs/older-downloads/). +1. Download and install [Intel MKL](https://software.intel.com/en-us/mkl/choose-download/windows) (registration required). +1. Download and install [NVIDIA CUDA](https://developer.nvidia.com/cuda-downloads?target_os=Windows&target_arch=x86_64&target_version=10&target_type=exelocal). +1. Install MXNet with MKL support with pip: + +```bash +pip install mxnet-cu92mkl +``` + +Once you have installed a version of MXNet, [validate your MXNet installation with Python](validate_mxnet.md). + +### 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](#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](https://pypi.org/project/mxnet/). + +![pip packages](https://raw.githubusercontent.com/dmlc/web-data/master/mxnet/install/pip-packages-1.3.0.png) + + +## Build from Source + +**IMPORTANT: It is recommended that you review the [build from source guide](build_from_source.md) 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](https://www.visualstudio.com/downloads/) or [Microsoft Visual Studio 2015](https://www.visualstudio.com/vs/older-downloads/). + +**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 MKLDNN. In this case it is recommended that you refer to the [MKLDNN_README](https://github.com/apache/incubator-mxnet/blob/master/MKLDNN_README.md). + +**Option 1: Build with Microsoft Visual Studio 2017 (VS2017)** + +To build and install MXNet yourself using [VS2017](https://www.visualstudio.com/downloads/), you need the following dependencies. You may try a newer version of a particular dependency, but please open a pull request or [issue](https://github.com/apache/incubator-mxnet/issues/new) to update this guide if a newer version is validated. + +1. Install or update VS2017. + - If [VS2017](https://www.visualstudio.com/downloads/) 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 +1. Follow the [instructions for opening the Visual Studio Installer](https://docs.microsoft.com/en-us/visualstudio/install/modify-visual-studio) to modify `Individual components`. +1. 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`. +1. 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](https://cmake.org/download) if it is not already installed. [CMake v3.12.2](https://cmake.org/files/v3.12/cmake-3.12.2-win64-x64.msi) has been tested with MXNet. +1. Download and run the [OpenCV](https://sourceforge.net/projects/opencvlibrary/files/opencv-win/3.4.1/opencv-3.4.1-vc14_vc15.exe/download) 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. +1. This will unzip several files. You can place them in another directory if you wish. +1. Set the environment variable `OpenCV_DIR` to point to the OpenCV build directory that you just unzipped (e.g., `OpenCV_DIR = C:\utils\opencv\build`). +1. If you don’t have the Intel Math Kernel Library (MKL) installed, you can install it and follow the [MKLDNN_README](https://github.com/apache/incubator-mxnet/blob/master/MKLDNN_README.md) from here, or you can use OpenBLAS. These instructions will assume you're using OpenBLAS. +1. Download the [OpenBlas](https://sourceforge.net/projects/openblas/files/v0.2.19/OpenBLAS-v0.2.19-Win64-int32.zip/download) 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. +1. Unzip the file. You can place the unzipped files and folders in another directory if you wish. +1. Set the environment variable `OpenBLAS_HOME` to point to the OpenBLAS directory that contains the `include` and `lib` directories (e.g., `OpenBLAS_HOME = C:\utils\OpenBLAS`). +1. Download and install [CUDA](https://developer.nvidia.com/cuda-downloads?target_os=Windows&target_arch=x86_64&target_version=10&target_type=exelocal). If you already had CUDA, then installed VS2017, you should reinstall CUDA now so that you get the CUDA toolkit components for VS2017 integration. +1. Download and install cuDNN. To get access to the download link, register as an NVIDIA community user. Then Follow the [link](http://docs.nvidia.com/deeplearning/sdk/cudnn-install/index.html#install-windows) to install the cuDNN. +1. Download and install [git](https://git-for-windows.github.io/) if you haven't already. After you have installed all of the required dependencies, build the MXNet source code: -1. Download the MXNet source code from [GitHub](https://github.com/apache/incubator-mxnet). Don't forget to pull the submodules: +1. Start ```cmd``` in windows. +2. Download the MXNet source code from GitHub by using following command: ``` - git clone https://github.com/apache/incubator-mxnet.git --recursive +cd C:\ +git clone https://github.com/apache/incubator-mxnet.git --recursive ``` -2. Start a Visual Studio command prompt. -3. Use [CMake](https://cmake.org/) to create a Visual Studio solution in ```./build``` or some other directory. Make sure to specify the architecture in the -[CMake](https://cmake.org/) command: +3. 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. +4. Create a build dir using the following command and go to the directory, for example: ``` - mkdir build - cd build - cmake -G "Visual Studio 14 Win64" .. +mkdir C:\build +cd C:\build ``` -4. 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. +5. 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" +``` +**Note**: you may add to the cmake compilation options the compiler version to use with: `-T version=14.11` +6. 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](https://www.visualstudio.com/vs/older-downloads/), you need the following dependencies. You may try a newer version of a particular dependency, but please open a pull request or [issue](https://github.com/apache/incubator-mxnet/issues/new) to update this guide if a newer version is validated. + +1. If [Microsoft Visual Studio 2015](https://www.visualstudio.com/vs/older-downloads/) 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](https://cmake.org/) if it is not already installed. +3. Download and install [OpenCV](http://sourceforge.net/projects/opencvlibrary/files/opencv-win/3.0.0/opencv-3.0.0.exe/download). +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](http://sourceforge.net/projects/openblas/files/v0.2.14/). +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](https://developer.nvidia.com/cuda-downloads?target_os=Windows&target_arch=x86_64) and [cuDNN](https://developer.nvidia.com/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](https://github.com/apache/incubator-mxnet) (make sure you also download third parties submodules e.g. ```git clone --recurse-submodules```). +2. Use [CMake](https://cmake.org/) 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](http://jupyter.readthedocs.io/) used for running MXNet tutorials and examples. - Install ```graphviz``` by downloading MSI installer from [Graphviz Download Page](https://graphviz.gitlab.io/_pages/Download/Download_windows.html). **Note** Make sure to add graphviz executable path to PATH environment variable. Refer [here for more details](http://stackoverflow.com/questions/35064304/runtimeerror-make-sure-the-graphviz-executables-are-on-your-systems-path-aft) - Install ```Jupyter``` by installing [Anaconda for Python 2.7](https://www.anaconda.com/download/) -**Note** Do not install Anaconda for Python 3.5. MXNet has few compatibility issue with Python 3.5. - -  +**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: - [Python](#install-the-mxnet-package-for-python) @@ -68,6 +207,8 @@ We have installed MXNet core library. Next, we will install MXNet interface pack ## Install MXNet 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](https://www.python.org/downloads/release/python-2712/). 2. Install ```Numpy``` using windows installer available [here](https://scipy.org/index.html). 3. Next, we install Python package interface for MXNet. You can find the Python interface package for [MXNet on GitHub](https://github.com/dmlc/mxnet/tree/master/python/mxnet). @@ -77,31 +218,22 @@ We have installed MXNet core library. Next, we will install MXNet interface pack cd python sudo python setup.py install ``` -Done! We have installed MXNet with Python interface. Run below commands to verify our installation is successful. -```bash - # Open Python terminal - python - # You should be able to import mxnet library without any issues. - >>> import mxnet as mx; - >>> a = mx.nd.ones((2, 3)); - >>> print ((a*2).asnumpy()); - [[ 2. 2. 2.] - [ 2. 2. 2.]] -``` -We actually did a small tensor computation using MXNet! You are all set with MXNet on your Windows machine. +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](#next-steps). ## Install the MXNet Package for R MXNet for R is available for both CPUs and GPUs. -### Installing MXNet on a Computer with a CPU Processor +### 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 with the Prebuilt Binary Package(CPU) +#### 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. @@ -114,7 +246,7 @@ For CPU-only package: install.packages("mxnet") ``` -#### Building MXNet from Source Code(CPU) +#### Building MXNet-R from Source Code(CPU) 1. Clone the MXNet github repo. ```sh @@ -193,7 +325,7 @@ R CMD INSTALL --build --no-multiarch R-package ``` -### Installing MXNet on a Computer with a GPU Processor +### 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 @@ -210,7 +342,7 @@ However, a few dependencies remain for both options. You will need the followin Note: A pre-requisite to above softwares is [Nvidia-drivers](http://www.nvidia.com/Download/index.aspx?lang=en-us) which we assume is installed. -#### Installing MXNet with the Prebuilt Binary Package(GPU) +#### 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. @@ -223,7 +355,8 @@ For GPU package: 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 from Source Code(GPU) + +#### 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. @@ -324,9 +457,10 @@ You might want to add this command to your ```~/.bashrc``` file. If you do, you For more details about installing and using MXNet with Julia, see the [MXNet Julia documentation](http://dmlc.ml/MXNet.jl/latest/user-guide/install/). + ## Installing the MXNet Package for Scala -Scala-MXNet is not yet available for Windows. +MXNet-Scala is not yet available for Windows. ## Next Steps