Skip to content

Setup CNTK on Windows

Jump to bottom
Wolfgang Manousek edited this page Jan 17, 2017 · 183 revisions

If you want to build CNTK from source code on Windows using Visual Studio 2015, this page is for you.

If you are looking for any other kind of support in setting up a CNTK build environment or installing CNTK on your system, you should go here instead.

For Your Consideration

Here are recommendations to make sure you can build CNTK successfully:

  • The system locale on the build machine should be set to a language with a 'latin' based character set.
  • Avoid extremely long path names. The build procedure uses copy-operations (XCOPY) that can run into problems with path expression with over 256 characters in length.
  • CNTK requires Visual Studio 2015 Update 3 to build. If you have other versions of Visual Studio installed on your system, please make sure they are not mentioned ahead of the VS2015 tools in your path environment variable.

And now let's proceed to the setup.

64-bit OS

CNTK requires a 64-bit Windows installation. We tested the build process on Windows 8.1, Windows 10, and Windows Server 2012 R2 and later. Other environments are not officially supported. For compatibility issues check CNTK Production Build and Test configuration.

Environment Variables

Building CNTK on your system requires the definition and configuration of various environment variables. For an overview of the environment variables used by the Windows build of CNTK please see this page.

Visual Studio 2015 with Update 3

Install Microsoft Visual Studio 2015.3 for Windows. A link to the download can be found here. Please install Visual Studio 2015, not a previous version or the 2017-Preview! The Community Version of Visual Studio 2015 is sufficient to build CNTK.

During the installation process please select custom installation:

im1

On the feature selection screen make sure you add 'Common Tools for Visual C++ 2015' to your installation:

im1

Pre-Existing Visual Studio 2015 installation

If you already have VS 2015 installed, make sure you are on Update 3. See the Help->About menu to display the version number like "Version 14.0.25431.01 Update 3".

You are also required to have the 'Common Tools for Visual C++ 2015' installed on your system. To check open the Windows "Control Panel -> Programs -> Programs and Features' and select 'Microsoft Visual Studio Enterprise 2015 with Updates' from the list of installed programs. This will start the Visual Studio setup again and allows you to make sure the 'Common Tools for Visual C++ 2015' feature is installed on your system (see picture above).

Git

Git is required to work with the CNTK code base. You may use the following methods:

You may also consider the following Git packages:

  • Git for Windows. During the installation make sure you set the option "Checkout Windows-style, commit UNIX-style line endings" at the "Configuring line endings" prompt.
  • GitHub Desktop client

MKL

The default CNTK math library is the Intel Math Kernel Library (MKL). CNTK uses Intel MKL through a custom library version ("CNTK custom MKL"), allowing you to build CNTK without downloading the complete Intel MKL software distribution. The custom version of MKL for CNTK contains just the functionality used by CNTK and is therefore much smaller. If you want to build with the complete Intel MKL distribution, you will need to adapt the CNTK build process. 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 the file CNTKCustomMKL-Windows-3.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\3 (the top-level folder inside the ZIP archive is called 3). For more information, see the CNTK web site.

Note: if you want to build older 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 specify the CNTKCustomMKL version to use.

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 Download button, and then select both msmpisdk.msi and MSMpiSetup.exe.

You need to download and install both Run-time and SDK (files msmpisdk.msi and MSMpiSetup.exe). 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. We will migrate most likely in the near future to this version.

Boost

Follow these steps to install the Boost Library on your system:

  • Download and install Boost version 1.60 (you need the msvc-14.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-msvc-14.0
  • Set the environment variable BOOST_LIB_PATH to the Boost libraries, e.g.:
    setx BOOST_LIB_PATH c:\local\boost_1_60_0-msvc-14.0\lib64-msvc-14.0
  • To integrate the Boost test framework into Visual Studio you can install a runner for Boost tests in Visual Studio from the Visual Studio Gallery.

Protobuf

You need a version of Protobuf 3.1.0 compiled for CNTK. You can compile this version by yourself, or use an already (precompiled) prepared version of Protobuf 3.1.0 (described on this page). If you want to build the Protobuf library for CNTK on your system, you can find the details here

Download the ZIP file containing the precompiled version of Protobuf for CNTK from this location

Extract the archive to a folder on your local disk, e.g. to C:\local\protobuf-3.1.0-vs15 and set the environment variable PROTOBUF_PATH pointing to that location, e.g.:

    setx PROTOBUF_PATH c:\local\protobuf-3.1.0-vs15

Quick installation check: If you followed the instruction above and used the same paths, the command dir C:\local\protobuf-3.1.0-vs15\bin will succeed.

GPU Specific Packages

This section outlines the packages you need to setup in order for CNTK to leverage NVIDIA 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 to use CNTK GPU capabilities. You can check whether your card is CUDA-compatible here and here (for older cards). Your GPU card Compute Capability (CC) must be 3.0 or more.

In the following steps we will install the NVidia development tools required to build the Microsoft Cognitive Toolkit as well as NVidia support libraries. As the last step (after you installed all these mentioned NVidia tools!), you should check that you have the latest graphic card driver installed.

NVIDIA CUDA 8

Important In case you have a first-time Visual Studio 2015 installation as described above, you will need to install NVIDIA CUDA 8 now, even if you have already an existing installation of CUDA 8! The NVIDIA CUDA 8 installation adds support to the NVIDIA development tools to the Visual Studio environment, which is required to build CNTK successfully.

CNTK is set to build with CUDA 8.0. Download and install the NVIDIA CUDA 8.0 Toolkit:

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

CUDA_PATH="C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v8.0"
CUDA_PATH_V8_0="C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v8.0"

cuDNN

Install NVIDIA CUDA Deep Neural Network library also known as cuDNN in the version NVIDIA: cuDNN v5.1 for CUDA 8.0 from this link. This version is suitable for Windows 8.1, Windows 10, as well as Windows Server 2012 R2 and later.

  • Extract the archive to a folder on your local disk, e.g. to C:\local\cudnn-8.0-v5.1\ and set the environment variable CUDNN_PATH pointing to that location, e.g.:
    setx CUDNN_PATH C:\local\cudnn-8.0-v5.1\cuda
  • Quick installation check: If you followed the instruction above and used the same paths, the command dir C:\local\cudnn-8.0-v5.1\cuda\include\cudnn.h will succeed.

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 (we assume c:\local\cub-1.4.1) and set the environment variable CUB_PATH pointing to that location, e.g.:
    setx CUB_PATH c:\local\cub-1.4.1\
  • Quick installation check. If you followed the instruction above and used the same paths, this command dir C:\local\cub-1.4.1\cub\cub.cuh will succeed.

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

This completes the 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. In the following we assume SWIG_PATH=c:\local\swigwin-3.0.10 as the installation path.

  • If you do not have an Anaconda installation: install Anaconda Python for Windows. You can follow the standard configuration given in the install program (InstallationType=JustMe; AddToPath=No; RegisterPython=No). In the following we assume you installed Python into C:\local\Anaconda3-4.1.1-Windows-x86_64. If you installed Python in a different directory, please adjust the commands given below accordingly.

  • If you already have a CNTK Python environment (called cntk-py34) you can update it with the latest required packages with the following commands:

    cd C:\local\Anaconda3-4.1.1-Windows-x86_64\scripts
    conda env update --file [CNTK repo root]\scripts\install\windows\conda-windows-cntk-py34-environment.yml --name cntk-py34
    activate C:\local\Anaconda3-4.1.1-Windows-x86_64\envs\cntk-py34
  • In your Anaconda installation, create a conda environment (called cntk-py34 here) and activate it by running the following commands from the Windows command shell:
    cd C:\local\Anaconda3-4.1.1-Windows-x86_64\scripts
    conda env create --file [CNTK repo root]\scripts\install\windows\conda-windows-cntk-py34-environment.yml
    activate C:\local\Anaconda3-4.1.1-Windows-x86_64\envs\cntk-py34

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

Step 2: IMPORTANT! Uninstall previous CNTK Python package -- follow both steps carefully

  • If you previously installed any version of the CNTK Python package on your machine, uninstall it by first removing any CNTK related paths in the PYTHONPATH environment variable. Do: echo %PYTHONPATH% to see its current value, and then use the setx command to set PYTHONPATH such that the CNTK related paths are gone. If that makes PYTHONPATH empty, so be it.
  • Do the uninstall: pip uninstall cntk

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

  • Change into the [CNTK clone root]\Tutorials\NumpyInterop directory and run the FeedForward example with python FeedForwardNet.py. You will see the 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

  • If you want to use Python Tools for Visual Studio (PTVS):
  • First determine your path to Visual studio (like: "c:\Program Files (x86)\Microsoft Visual Studio 14.0"). Take that path and create an environment variable named MYVSPATH. set MYVSPATH=thePathToVSDescribedAbove.
  • Next get the path to your CNTK installation (take a look in c:\local). For example if you installed CNTK2.0Beta5, you would have a path like: c:\local\CNTK-2-0-beta5-0-Windows-64bit-GPU. Take that path and create an environment variable named MYCNTKPATH. set MYCNTKPATH=thePathToCNTKDescribedAbove.
  • Next Setup your environment with %MYVSPATH%\vc\vcvarsall.bat" amd64.
  • Next update your PATH environment with set PATH=%MYCNTKPATH%\cntk\cntk;%PATH%.
  • Then open Visual Studio with %MYVSPATH%\Common7\IDE\devenv.exe
  • In VS, go to Tools -> Python Tools -> Python Environments and create a new environment.
  • Select Configure from the dropdown menu and set the prefix path to C:\local\Anaconda3-4.1.1-Windows-x86_64\envs\cntk-py34\.
  • Afterwards, click Auto Detect and the rest of the entries will be filled out automatically.

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:\local" under the "Extract to". We recommend that you rename the created OpenCV folder to reflect the version number you just installed (Opencv3.1.0)

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

setx OPENCV_PATH_V31 c:\local\Opencv3.1.0\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.

zlib and libzip

If you are building CNTK with ZLib and LibZip, you will need to recompile these packages. You can compile this version by yourself, or use an already (precompiled) prepared version (described on this page). If you want to build the libzip/zlib compression library for CNTK on your system, you can find the details here

Download the ZIP file containing the precompiled version of libzip/zlib compression library for CNTK from this location

  • Extract the archive to a folder on your local disk, e.g. to C:\local\zlib-vs15 and set the environment variable ZLIB_PATH pointing to that location, e.g.:
    setx ZLIB_PATH c:\local\zlib-vs15
  • Quick installation check: If you followed the instruction above and used the same paths, the command dir C:\local\zlib-vs13\bin will succeed and show a couple of DLLs.

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 repository folder (we use c:\repos for examples at this page) and execute the following command:
git clone https://github.com/Microsoft/cntk
git submodule update --init Source/Multiverso
  • Within Visual Studio use the following path for the repository to clone:
https://github.com/Microsoft/cntk

Submodule Multiverso is used for enable DataParallelASGD for training.

OPTIONAL If you don't need DataParallelASGD support, then add the environment variable CNTK_ENABLE_ASGD and set its value to false. E.g. run this in an CMD prompt, and then reopen your CMD shell(s) and Visual Studio to pick up the change:

setx CNTK_ENABLE_ASGD false

If you already built CNTK, you just need to rebuild the SGDLib Project (right-click, Project Only -> Rebuild Only SGDLib). Then perform the build as usual.

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.

Quick test of CNTK build functionality

To ensure that CNTK is working properly in your system, you can quickly run an example from the Hello World - Logistic Regression tutorial. 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 change to the Tutorials\HelloWorld-LogisticRegression directory:
set PATH=C:\repos\cntk\x64\release;%PATH%
cd C:\repos\cntk\Tutorials\HelloWorld-LogisticRegression

First try the example:

cntk configFile=lr_bs.cntk makeMode=false

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.

Trying CNTK with GPU

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

cntk configFile=lr_bs.cntk makeMode=false deviceId=auto

Near the beginning of the output you should see a line confirming a GPU was used:

Model has 9 nodes. Using GPU 0.

Note that GPU ID may be different. The deviceId parameter defines what processor to use for computation.

  • 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

Trying the CNTK Python API

We assume that you created a CNTK Python environment (either through the install script or manually). Open a command prompt and activate your CNTK python environment by executing activate cntk-py34. As a quick test go to the Tutorials\NumpyInterop folder and run python FeedForwardNet.py. After training you should see an output similar to this:

Finished Epoch [1]: loss = 0.297748 * 25600 2.383s (10742.8 samples per second)
 error rate on an unseen minibatch 0.040000

Debugging CNTK source code in Visual Studio

To debug the 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

New Documentation Site

Iteration Plans

Clone this wiki locally