Skip to content

Setup CNTK on Windows

Jump to bottom Edit New page
Alexey Reznichenko edited this page Oct 28, 2016 · 110 revisions

This page describes how to get set up with source code and building CNTK yourself. If you are only interested in the binary installation, look here instead.

CNTK Production Build and Test configuration

CNTK may be successfully run in many Windows configurations, but in case you want to avoid possible compatibility issues you may get yourself familiar with the CNTK Production Build and Test configuration where we list all dependency components and component versions that we use.

Known limitations

IMPORTANT! There are some limitations in the CNTK build machine configuration. We are working on fixing this, but for the time being please ensure the following:

  • System locale on Build Machine is set to English (known bug)
  • Do not use very long paths to CNTK code and build directories. Build procedure uses XCOPY that sometimes has issues with the paths over 256 characters
  • We found that if you have Visual Studio 2013 and Visual Studio 2012 or Visual Studio 2010 installed simultaneously it may cause build failures. Therefore we recommend to have a "clean" installation of Visual Studio 2013.

And now let's proceed to the setup.

64-bit OS

You need a 64-bit Windows installation to use CNTK.

OPTIONAL. Setting all required environment variables in batch mode

Almost all installation procedures described below involve some manual environment variables setting. In case you accept the default/suggested paths for the required prerequisite components, you may set all required environment variables by creating a batch file with the code below and running it (you need to run this procedure as Administrator). The set of the variables imply that you install all mandatory and optional components for GPU enabled configuration using MKL as Math library. The commands below also create some basic root directories used as example paths at this page. If you do not need it at this stage, omit all mkdir commands.

mkdir c:\src
mkdir c:\local
mkdir c:\NVIDIA\cudnn-5.1
mkdir c:\zip
mkdir c:\local\CNTKCustomMKL
setx           CUDA_PATH "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v7.5"
setx      CUDA_PATH_V7_5 "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v7.5"
setx            CUB_PATH c:\src\cub-1.4.1\
setx          CUDNN_PATH C:\NVIDIA\cudnn-5.1\cuda
setx  BOOST_INCLUDE_PATH c:\local\boost_1_60_0
setx      BOOST_LIB_PATH c:\local\boost_1_60_0\lib64-msvc-12.0
setx       CNTK_MKL_PATH c:\local\CNTKCustomMKL
setx     OPENCV_PATH_V31 C:\src\opencv\build
setx           ZLIB_PATH C:\zip
setx       PROTOBUF_PATH c:\local\protobuf-3.1.0

Depending on your configuration, you may also need this:

setx CNTK_ENABLE_1BitSGD true

If Visual Studio is currently open, please close it and open it again so it picks up your new environment variables.

After completing the installation steps below, you may verify that the required PATH environment variables were set by running the following set of commands:

dir "%CUDA_PATH%"
dir "%CUDA_PATH_V7_5%"
dir %CUB_PATH%
dir %CUDNN_PATH%
dir %BOOST_INCLUDE_PATH%
dir %BOOST_LIB_PATH%
dir %CNTK_MKL_PATH%\2
dir %OPENCV_PATH_V31%
dir %ZLIB_PATH%
dir %PROTOBUF_PATH%

You may also run the commands above at the end of the component installation to ensure all paths contain the required files.

Visual Studio 2013 with Update 5

Install Microsoft Visual Studio 2013 (not 2015) with Update 5. You may use this link - see section How to obtain Visual Studio 2013 Update 5. You may use any edition.

If you already have VS 2013 installed, make sure you have Update 5. Help->About should show a version number like "Version 12.0.40629.00 Update 5". CNTK requires this update. Without it you will get compilation errors related to initializer lists for std::array. Update 5 may be installed using any of the following methods:

  • Start Visual Studio and go the following Menu: Tools -> Extensions and Updates -> Updates -> Product Updates -> Visual Studio 2013 Update 5.
  • Download the Update 5 for Visual Studio 2013.

IMPORTANT Today CNTK is designed to be compiled with Visual Studio 2013 with Update 5. Though it is possible to compile with other Visual Studio versions, it may require extra debugging and configuration work. Also in case of GPU configurations be aware that NVIDIA CUDA 7.5 does NOT support Visual Studio versions higher than 2013 as described here (Section 1.1, Table 2).

OPTIONAL If you want to contribute in the Examples/CNTKv2 project you will need Python Tools for Visual Studio. Download the MSI file for your Visual Studio version from the PTVS 2.2.2 page.

Git

You need to have Git installed to work with the CNTK code base. You may use the following methods:

You may also consider the following Git packages:

MKL

The default CNTK math library is the Intel Math Kernel Library (Intel MKL) (link). CNTK supports using the Intel MKL via a custom library version ("CNTK custom MKL").

IMPORTANT You can NOT directly build CNTK using a regular installed Intel MKL SDK, the build is configured to work with a custom generated CNTK custom MKL library (This way you don't need to go through the process of installing the complete Intel MKL SDK). You can obtain the CNTK custom MKL library if you follow the steps below. If you need to build your own custom version, you can find the needed information here.

Installing the CNTK custom MKL library:

  • Create a directory on your machine to hold CNTK custom MKL versions, e.g.:
mkdir c:\local\CNTKCustomMKL
  • Set the environment variable CNTK_MKL_PATH to point to this directory:
setx CNTK_MKL_PATH c:\local\CNTKCustomMKL

  • Download this file: CNTKCustomMKL-Windows-2.zip. Unzip it into your CNTK MKL path, creating a numbered sub directory within. For example, if you are on latest master, download and extract its contents to c:\local\CNTKCustomMKL\2 (the top-level folder inside the ZIP archive is called 2). For more information, see the CNTK web site.

    Note: if you want to build other CNTK source versions, you may need to install alternate CNTK custom MKL versions. Check the tag <CNTKCustomMKLVersion> in the CNTK build properties file CNTK.Cpp.props to determine which.

MS-MPI

Install version 7 (7.0) of Microsoft MPI (MS-MPI), a Microsoft implementation of the Message Passing Interface standard, from this download page. Click on the red Download button, and then select both msmpisdk.msi and MSMpiSetup.exe.

IMPORTANT!

  • You need to download and install both Run-time and SDK (files msmpisdk.msi and `MSMpiSetup.exe``)
  • Currently CNTK requires version 7.0.12437.6 (marked simply as "Version 7" in the title of the correspondent download page). Version 7.1 is not yet fully tested and may results in different compile and run-time errors.

Boost Library

We are using Boost Library for unit tests and for the CNTK Image Reader. We are probably going to incorporate the Boost library into CNTK code in the future. But today you are required to install it manually:

  • Download and install Boost version 1.60 (you need msvc-12.0 binaries) from this download location on Sourceforge.
  • Set the environment variable BOOST_INCLUDE PATH to your Boost installation, e.g.:
setx BOOST_INCLUDE_PATH c:\local\boost_1_60_0
  • Set the environment variable BOOST_LIB_PATH to the Boost libraries, e.g.:
setx BOOST_LIB_PATH c:\local\boost_1_60_0\lib64-msvc-12.0
  • To integrate Boost into the Visual Studio Test Framework you can install a runner for Boost tests in Visual Studio from the Visual Studio Gallery.

Protobuf

We use Protocol Buffers for serialization.

The following steps assume that the protobuf sources have been unzipped to `c:\sources\protobuf-3.1.0'. This folder can be removed after installation. If the location differs in your case please adapt correspondingly in the steps below.

  1. Open a command line and run "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" amd64

  2. Create a build directory:  

cd C:\sources\protobuf-3.1.0\cmake
C:\sources\protobuf-3.1.0\cmake>mkdir build && cd build
  1. Create a debug build: 
C:\sources\protobuf-3.1.0\cmake\build>mkdir debug && cd debug
C:\sources\protobuf-3.1.0\cmake\build\debug>cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Debug -Dprotobuf_BUILD_TESTS=OFF -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -DCMAKE_INSTALL_PREFIX="c:\local\protobuf-3.1.0" ..\..
C:\sources\protobuf-3.1.0\cmake\build\debug>nmake && nmake install && cd ..
  1. Create a release build:
C:\sources\protobuf-3.1.0\cmake\build>mkdir release && cd release
C:\sources\protobuf-3.1.0\cmake\build\release>cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -Dprotobuf_BUILD_TESTS=OFF -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -DCMAKE_INSTALL_PREFIX="c:\local\protobuf-3.1.0" ..\..
C:\sources\protobuf-3.1.0\cmake\build\release>nmake && nmake install && cd ..
  1. Set the environment variable PROTOBUF_PATH to the protobuf location (Note: this is the install location used in the cmake command above, not the sources location.):
setx PROTOBUF_PATH c:\local\protobuf-3.1.0

GPU Specific Packages

This section outlines the packages you need to setup in order for CNTK to leverage GPUs.

If you do NOT intend to use any GPUs with CNTK and will rely on the CPU only, you may skip directly to the next general section. Otherwise proceed further.

Checking your GPU compatibility

You need a CUDA-compatible graphic card available to use CNTK GPU capabilities. You can check whether your card is CUDA-compatible here and here (for older cards).

IMPORTANT. CNTK uses cuDNN library for GPU acceleration. Because of this your GPU card Compute Capability (CC) should be 3.0 or more. Using cards with lesser CC revision will very likely result in the incorrect processing results (like described in this issue - see Question 3 in the initial post). You may check the CC revision of your cards using links to compatibility pages from the previous paragraph.

IMPORTANT! Do NOT update your GPU card driver at this step because with the high probability it will be replaced by the CUDA installation procedure. This will be the case even if your system contains the driver newer, than the one included in the CUDA installation. This guide will instruct you to update the driver at a later step.

CUDA 7.5

IMPORTANT. Currently CNTK is set to be built with CUDA 7.5. Building it with higher versions of CUDA may result in build errors.

Download and install the NVIDIA CUDA 7.5 Toolkit:

IMPORTANT! CUDA installation will propose to install a certain version of the Graphics Driver. Accept this selection even if you have a newer driver installed. Otherwise the GPU Deployment Kit component required by CNTK will NOT be installed. You will install the latest Graphics Driver in the next section.

Make sure that the following CUDA environment variables are set to the correct path (the installer will create these for you). Default installation paths are assumed:

CUDA_PATH="C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v7.5"
CUDA_PATH_V7_5="C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v7.5"

Latest GPU card driver

Now install the latest driver for your GPU card:

  • Select your card and download the driver pack from this download location
  • Run the driver installation procedure

CUB

Get and install NVIDIA CUB.

IMPORTANT! Install NVIDIA CUB using the exact version specified below. This is necessary because it is expected by the CNTK build configuration program.

  • Download NVIDIA CUB v.1.4.1 from this download link
  • Extract the archive to a folder on your local disk and set the environment variable CUB_PATH pointing to that location, e.g.:
setx CUB_PATH c:\src\cub-1.4.1\
  • Quick installation check. If you followed the instruction above and used the same paths, this command dir C:\src\cub-1.4.1\cub\cub.cuh should succeed.

cuDNN

Install NVIDIA CUDA Deep Neural Network library (cuDNN).

IMPORTANT! Install cuDNN using the exact version specified below. This is necessary because it is expected by the CNTK build configuration program.

  • Download the Windows version of cuDNN v5.1 for Windows 10 or Windows 7 / Windows 8.1.

  • Extract the archive to a folder on your local disk, e.g. to c:\NVIDIA\cudnn-5.1 and set the environment variable CUDNN_PATH pointing to that location, e.g.:

setx CUDNN_PATH C:\NVIDIA\cudnn-5.1\cuda
  • Quick installation check. If you followed the instruction above and used the same paths, the command dir C:\NVIDIA\cudnn-5.1\cuda\include\cudnn.h should succeed.

This completes GPU Specific section

OPTIONAL. CNTK v2 Python support.

This section describes how to build CNTK v2 with Python support.

Step 1: Build Python

  • Install SWIG 3.0.10:

  • Install Anaconda recommended (Anaconda Python 3.4) or create a Python 3.4.3 environment within your existing Python Anaconda or miniconda installation using the following commands:

conda create --name cntk-py34 python=3.4.3 numpy scipy jupyter matplotlib pillow

activate cntk-py34

[Note: Make sure that the python version installed above is what you use for the remainder of the instructions.]

Step 2: Uninstall previous CNTK Python package

  • If you previously installed any version of the CNTK Python package on your machine, uninstall it by running: pip uninstall cntk-py34

Step 3: Building python package We are going to build the Python module using the CNTK Visual Studio solution, CNTK.sln.

(a) Set up build environment variables

setx SWIG_PATH [path to the folder containing swig.exe]
setx CNTK_PY34_PATH [paths for your Python 3.4 environment]

-Note: the value for the CNTK_PY34_PATH environment variable can be determined by running conda ..activate cmd.exe [name-or-path-of-your-environment] For example, run conda ..activate cmd.exe cntk-py34, if you have set up the Python environment as suggested above.

(b) Build the binaries

  • Make sure that Visual Studio sees the updated environment variables by starting the solution file after setting the aforementioned environment variables.

  • Build a Release configuration in the CNTK Visual Studio solution, CNTK.sln. This will build the CNTK Python module inside bindings\python\cntk and also produce a package (.whl) in a subfolder Python of your build output folder (e.g., x64\Release\Python).

  • Make sure your path includes the build output folder (e.g., x64\Release), and that PYTHONPATH includes the bindings\python directory:

(c) Set python code/ build paths

setx PYTHONPATH [CNTK repo root]\bindings\python\;%PYTHONPATH%
setx PATH [CNTK repo root][build output directory];%PATH%

Note: in contrast to the setup shown for the Pip package installation, here we will load the CNTK module from the CNTK repository clone, not as an installed package in your Python environment. (Hence also the difference in setting up PYTHONPATH)

Step 4: Verify setup

Python

  • Run the examples from inside the [CNTK clone root]\bindings\python directory, to verify your installation. Run python examples\NumpyInterop\FeedForwardNet.py. You should following output on the console:
Minibatch: 0, Train Loss: 0.7915553283691407, Train Evaluation Criterion: 0.48

Minibatch: 20, Train Loss: 0.6266774368286133, Train Evaluation Criterion: 0.48

Minibatch: 40, Train Loss: 1.0378565979003906, Train Evaluation Criterion: 0.64

Minibatch: 60, Train Loss: 0.6558118438720704, Train Evaluation Criterion: 0.56

Note: If you see an error saying "RuntimeError: module compiled against API version 0xa but this version of numpy is 0x9", your numpy version is outdated and needs to be updated, run: pip install --upgrade numpy

OPTIONAL. OpenCV

If you want to build the CNTK Image Reader, you need to install Open Source Computer Vision (OpenCV).

(See also the next section if you want the Image Reader to support ZIP file format)

Download and install version 3.1 for Windows from this download location. This installer is just an unpacker. E.g. enter "c:\src" under the "Extract to".

Set the environment variable OPENCV_PATH_V31 pointing to the OpenCV build folder, e.g.

setx OPENCV_PATH_V31 C:\src\opencv\build

OPTIONAL. zlib and libzip

If you want to build the CNTK Image Reader, that supports ZIP File format, you need to install zlib and libzip libraries.

Please note, that you also need to install OpenCV to build CNTK Image Reader. See the previous section.

(The process described below is somewhat tedious and cumbersome. We currently are working on providing an easier option of enabling zlib and libzip and will publish it soon)*

We use the following installation paths in our instructions:

  • zlib sources: c:\zlib
  • libzip sources: c:\libzip
  • Build directory for zlib and libzip binaries: c:\zip

You can use any paths you like, but note the remark on target folder for binaries below

IMPORTANT! The following aspects are important:

  • Build commands for zlib and libzip should use the same target folder for binaries (specified via -DCMAKE_INSTALL_PREFIX parameter in cmake command below)
  • Build order is important. You should build zlib first because libzip is dependent on it
  • At the end of this section there will be instructions about renaming zlib.dll to zlib1.dll. Do NOT skip this step, otherwise you can get errors like described in this FAQ

Command prompt environment for build

Use VS2013 x64 Native Tools Command Prompt for executing all commands described below. You will find the correspondent shortcut in

%ProgramFiles(x86)%\Microsoft Visual Studio 12.0\Common7\Tools\Shortcuts

Building zlib

Execute the following commands from VS2013 x64 Native Tools Command Prompt:

cd c:\zlib
mkdir build
cd build
cmake .. -G"Visual Studio 12 2013 Win64" -DCMAKE_INSTALL_PREFIX="C:\zip"
msbuild /P:Configuration=Release INSTALL.vcxproj

Building libzib

Execute the following commands from VS2013 x64 Native Tools Command Prompt:

cd c:\libzip
mkdir build
cd build
cmake .. -G"Visual Studio 12 2013 Win64" -DCMAKE_INSTALL_PREFIX="C:\zip"
msbuild libzip.sln /t:zip /P:Configuration=Release
cmake -DBUILD_TYPE=Release -P cmake_install.cmake

MSBuild command above may generate some warnings. It is expected and may be ignored.

The last cmake command from the list above will generate the following error:

CMake Error at src/cmake_install.cmake:34 (file):
  file INSTALL cannot find "C:/libzip/build/src/Release/zipcmp.exe".

It is expected and may be ignored - all required binaries (zip.dll and zlib.dll) should be already in C:\zip\bin

Preparing the environment

  • Go to C:\zip\bin and rename zlib.dll to zlib1.dll (see Question 2 in zlib DLL FAQ for details)
  • Set the following environment variable:
setx ZLIB_PATH c:\zip

*: Build instructions in this section are based on the information from this post

Getting CNTK Source code

Before proceeding further, please note, that if you plan on making modifications to the CNTK code you should read the information on Developing and Testing in this Wiki.

Use Git to clone the CNTK Repository and access the source code.

  • If you use a standalone client, open Git command prompt, go to your source code folder (we use c:\src for examples at this page) and execute the following command:
git clone https://github.com/Microsoft/cntk
  • Within Visual Studio use the following path for the Repository to clone:
https://github.com/Microsoft/cntk

IMPORTANT! The procedure above does not provide you with the access to 1-bit Stochastic Gradient Descent (1bit-SGD) and BlockMomentumSGD components. If you want to build CNTK with this functionality enabled, please read the instructions on this page and then proceed with the installation.

Building CNTK

Open the CNTK solution and select the desired configuration:

  • Right-click the CNTK Solution in Solution Explorer and select Properties
  • In the appeared window select Configuration Properties and press Configuration Manager... button
  • In Configuration Manager select the desired configuration:
  • Debug or Release
  • GPU or CPU-only. CPU-only configurations are explicitly named. All other configurations imply GPU usage (i.e. Release means Release. GPU enabled mode)
  • You should always select CPU-only configurations if you have NOT installed the components required for GPU configurations
  • IMPORTANT! When you open CNTK Solution for the 1st time Debug_CpuOnly build configuration is selected by default. If you do NOT perform the steps above and just build the solution, you will get a debug build, and your GPU will not be used

Build the CNTK solution.

TODO

Brainscript (optional)

  • Please run the following self contained example:
cd C:\repos\CNTK\Examples\Other\Simple2d

CNTK configFile=Config/Simple.cntk currentDirectory=Data

You should be able to see the results getting printed on the console.

Quick test of CNTK build functionality

To ensure that CNTK is working properly in your system, you can quickly run Simple2d example from CNTK Examples set. This example trains a simple network and can be directed to use either CPU or GPU, which helps quickly ensure that CNTK is functioning properly.

Below we assume that the CNTK repository is cloned to c:\Repos\cntk and build\x64\release was used as a sub-directory for the build.

  • Open Command Prompt
  • Provide the path to the CNTK binaries (via Environment Variable or for Command Prompt session using the first command below) and switch to the Simple2d directory:
set PATH=C:\src\cntk\x64\release;%PATH%
cd C:\src\cntk\Examples\Other\Simple2d\Data

First try the example (note UNIX-style slashes in the config file path):

cntk configFile=../Config/Simple.cntk

If the sample runs, i.e. if there are no error messages, you will get an output related first to reading the configuration, followed by the output of the actual network training. Running the command a second time will report that the model has already been trained. To perform the training again, you must first remove the existing models by using the following command:

del ..\Output\Models\*.*

Trying CNTK with CPU

As seen previously, the Simple2d example produces an extensive output. Among this output there is the information regarding what processor was used for the Network Builder. If you perform the following command:

cntk configFile=../Config/Simple.cntk 1> out.txt 2>&1

and look for the string Builder Using in the resulting file out.txt you should be able to find this line

SimpleNetworkBuilder Using CPU

It tells us that CNTK was indeed using CPU.

Trying CNTK with GPU

If you built CNTK for GPU usage, try using GPU by executing the following command:

cntk configFile=../Config/Simple.cntk deviceId=auto 1> out.txt 2>&1

Look for the string Builder Using in the resulting file out.txt. In this case you should see:

SimpleNetworkBuilder Using GPU 0

Note that GPU id may be different. deviceId parameter defines what processor to use for Network Builder:

  • deviceId=-1 means use CPU. Default value
  • deviceId=X where X is an integer >=0 means use GPU X, i.e. deviceId=0 means GPU 0, etc.
  • deviceId=auto means use GPU, select GPU automatically

Debugging CNTK source code in Visual Studio

To debug the the source source code in CNTK with Visual Studio, follow the steps [here](Debugging CNTK source code in Visual Studio).

Contributing to CNTK code

If you plan modifications to the code you should read the information on Developing and Testing in this Wiki.

Next steps

Add a custom footer

Getting Started

Additional Documentation

How to use CNTK

Using CNTK Models in Your Code

Advanced topics

Licenses

Source Code & Development

Clone this wiki locally