Table Of Contents

Previous topic

Theano at a Glance

Next topic

Tutorial

This Page

Installing Theano

Note

If you are a member of LISA Labo, have a look at LISA Labo specific instructions for lab-specific installation instructions.

Requirements

In order to use Theano, the following libraries and software will need to be installed (MacOS and Windows users should refer to platform-specific instructions below for detailed installation steps):

Linux, Mac OS X or Windows operating system
We develop mainly on 64-bit Linux machines. other architectures are not well-tested.
Python >= 2.4
The development package (python-dev or python-devel on most Linux distributions) is recommended (see just below).
g++, python-dev
Not technically required but highly recommended, in order to compile generated C code. Theano can fall back on a NumPy-based Python execution model, but a C compiler allows for vastly faster execution. g++ >= 4.2 (for openmp that is currently always used) more recent version recommended!
NumPy >= 1.5.0
Earlier versions could work, but we don’t test it.
SciPy
Only currently required for sparse matrix and special functions support, but highly recommended. We recommend SciPy >=0.8 if you are using sparse matrices, because scipy.sparse is buggy in 0.6 (the scipy.csc_matrix version of dot() has a bug with singleton dimensions, there may be more bugs) and we do not run tests with 0.7.
A BLAS installation (with Level 3 functionality)
Including the development headers (-dev, -devel, depending on your Linux distribution). Mac OS X comes with the Accelerate framework built in, and various options exist for Windows (see below).

The following libraries and software are optional:

nose
Recommended, to run Theano’s test-suite.
Sphinx >= 0.5.1, pygments
For building the documentation. LaTeX and dvipng are also necessary for math to show up as images.
Git
To download bleeding-edge versions of Theano.
pydot
To be able to make picture of Theano computation graph.
NVIDIA CUDA drivers and SDK
Required for GPU code generation/execution. Only NVIDIA GPUs using 32-bit floating point numbers are currently supported.

Linux

CentOS 6

Easy Installation of an optimized Theano on CentOS 6 provides instructions on how to install Theano on CentOS 6, written by the Theano developers. It covers how to install Theano (for CPU-based computation only) with the distribution-packaged ATLAS, a free fast implementation of BLAS.

Ubuntu

Easy Installation of an optimized Theano on Ubuntu provides instructions on how to install Theano on Ubuntu. It covers how to install Theano with the distribution-packaged OpenBlas or ATLAS. Both are free fast implementation of BLAS.

Alternative installation on Gentoo

Brian Vandenberg emailed installation instructions on Gentoo, focusing on how to install the appropriate dependencies.

Nicolas Pinto provides ebuild scripts.

Alternative installation on Mandriva 2010.2

A contributor made rpm package for Mandriva 2010.2 of Theano 0.3.1.

Basic user install instructions

The easiest way to obtain the released version of Theano is from PyPI using pip (a replacement for easy_install provided by setuptools/distribute) by typing

pip install Theano

You may need to add sudo before this command to install into your system’s site-packages directory. If you do not have administrator access to your machine, you can install Theano locally (to ~/.local) using

pip install Theano --user

Alternatively you can use virtualenv to create an isolated site-packages directory; see the virtualenv documentation for details.

Note

Theano can be installed with easy_install, however we recommend pip. pip offers many benefits over easy_install such as more intelligent dependency management, better error messages and a pip uninstall command for easily removing packages.

If you do not have pip installed but do have easy_install, you can get pip by simply typing easy_install pip.

Updating Theano

The following command will update only Theano:

sudo pip install --upgrade --no-deps theano

The following command will update Theano and Numpy/Scipy (warning bellow):

sudo pip install --upgrade theano

If you installed NumPy/SciPy with yum/apt-get, updating NumPy/SciPy with pip/easy_install is not always a good idea. This can make Theano crash due to problems with BLAS (but see below). The versions of NumPy/SciPy in the distribution are sometimes linked against faster versions of BLAS. Installing NumPy/SciPy with yum/apt-get/pip/easy_install won’t install the development package needed to recompile it with the fast version. This mean that if you don’t install the development packages manually, when you recompile the updated NumPy/SciPy, it will compile with the slower version. This results in a slower Theano as well. To fix the crash, you can clear the Theano cache like this:

theano-cache clear

Bleeding-edge install instructions

Master Tests Status:

https://secure.travis-ci.org/Theano/Theano.png?branch=master

If you are a developer of Theano, then check out the Developer Start Guide.

If you want the bleeding-edge without developing the code you can use pip for this with the command line below. Note that it will also try to install Theano’s dependencies (like numpy and scipy), but not upgrade them. If you wish to upgrade them, remove the --no-deps switch to it, but go see a previous warning before doing this.

pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git

or (if you want to install it for the current user only):

pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git --user

The following are general instructions that will set you up with the bleeding-edge version of Theano and allow you to hack it. First, get the code using Git:

git clone git://github.com/Theano/Theano.git

From here, the easiest way to get started is (this requires setuptools or distribute to be installed):

cd Theano
python setup.py develop

Note

“python setup.py develop ...” does not work on Python 3 as it does not call the converter from Python 2 code to Python 3 code.

This will install a .pth file in your site-packages directory that tells Python where to look for your Theano installation (i.e. in the directory your just checked out of Github). Using develop mode is preferable to install as any modifications you make in the checkout directory (or changes you pull with Git) will be automatically reflected in the “installed” version without re-running python setup.py install.

If you do not have permission to modify your site-packages directory you can specify an alternative installation prefix using

python setup.py develop --prefix=~/.local

A common choice is ~/.local which is automatically searched for Python >= 2.6; for earlier Python versions and other installation prefixes, the prefix specified must contain lib/pythonA.B/site-packages, where A.B is e.g. 2.5, and this site-packages directory must be listed in PYTHONPATH.

An alternative, perhaps simpler way of creating and using an isolated site-packages is to use virtualenv; see the virtualenv documentation for details. If you find yourself using virtualenv frequently you may find the virtualenvwrapper package useful for switching between them.

Configuring PYTHONPATH

If import theano does not work in Python, you may need modify the environment variable PYTHONPATH accordingly. In bash, you may do this:

export PYTHONPATH=<new location to add>:$PYTHONPATH

In csh:

setenv PYTHONPATH <new location to add>:$PYTHONPATH

To make this change stick you will usually need to add the above command to your shell’s startup script, i.e. ~/.bashrc or ~/.cshrc. Consult your shell’s documentation for details.

Updating

To update your library to the latest revision, change directory (cd) to your Theano folder and execute the following command:

git pull

You should update frequently, bugs are fixed on a very regular basis.

Testing your installation

Once you have installed Theano, you should run the test suite. At a Python (or IPython) interpreter,

>>> import theano
>>> theano.test()

You can also run them in-place from the Git checkout directory by typing

theano-nose

You should be able to execute it if you followed the instructions above. If theano-nose is not found by your shell, you will need to add Theano/bin to your PATH environment variable.

Note

In Theano versions <= 0.5, theano-nose was not included. If you are working with such a version, you can call nosetests instead of theano-nose. In that case, some tests will fail by raising the KnownFailureTest Exception, and will be considered as errors, but they are nothing to worry about.

Note

The tests should be run with the configuration option device set to cpu (default). If you need to change this value, you can do that by setting the THEANO_FLAGS environment variable, by prefixing the theano-nose command with THEANO_FLAGS=device=cpu. If you have a GPU, it will automatically be used to run GPU-related tests.

If you want GPU-related tests to run on a specific GPU device, and not the default one, you should use init_gpu_device. For instance: THEANO_FLAGS=device=cpu,init_gpu_device=gpu1.

See config – Theano Configuration for more information on how to change these configuration options.

All tests should pass (skipped tests and known failures are normal). If some test fails on your machine, you are encouraged to tell us what went wrong on the theano-users@googlegroups.com mailing list.

Troubleshooting: Make sure you have a BLAS library

There are many ways to configure BLAS for Theano. This is done with the Theano flags blas.ldflags (config – Theano Configuration). The default is to use the BLAS installation information in NumPy, accessible via numpy.distutils.__config__.show(). You can tell theano to use a different version of BLAS, in case you did not compile numpy with a fast BLAS or if numpy was compiled with a static library of BLAS (the latter is not supported in Theano).

The short way to configure the Theano flags blas.ldflags is by setting the environment variable THEANO_FLAGS to blas.ldflags=XXX (in bash export THEANO_FLAGS=blas.ldflags=XXX)

The ${HOME}/.theanorc file is the simplest way to set a relatively permanent option like this one. Add a [blas] section with an ldflags entry like this:

# other stuff can go here
[blas]
ldflags = -lf77blas -latlas -lgfortran #put your flags here

# other stuff can go here

For more information on the formatting of ~/.theanorc and the configuration options that you can put there, see config – Theano Configuration.

Here are some different way to configure BLAS:

0) Do nothing and use the default config, which is to link against the same BLAS against which NumPy was built. This does not work in the case NumPy was compiled with a static library (e.g. ATLAS is compiled by default only as a static library).

1) Disable the usage of BLAS and fall back on NumPy for dot products. To do this, set the value of blas.ldflags as the empty string (ex: export THEANO_FLAGS=blas.ldflags=). Depending on the kind of matrix operations your Theano code performs, this might slow some things down (vs. linking with BLAS directly).

2) You can install the default (reference) version of BLAS if the NumPy version (against which Theano links) does not work. If you have root or sudo access in fedora you can do sudo yum install blas blas-devel. Under Ubuntu/Debian sudo apt-get install libblas-dev. Then use the Theano flags blas.ldflags=-lblas. Note that the default version of blas is not optimized. Using an optimized version can give up to 10x speedups in the BLAS functions that we use.

3) Install the ATLAS library. ATLAS is an open source optimized version of BLAS. You can install a precompiled version on most OSes, but if you’re willing to invest the time, you can compile it to have a faster version (we have seen speed-ups of up to 3x, especialy on more recent computers, against the precompiled one). On Fedora, sudo yum install atlas-devel. Under Ubuntu, sudo apt-get install libatlas-base-dev libatlas-base or libatlas3gf-sse2 if your CPU supports SSE2 instructions. Then set the Theano flags blas.ldflags to -lf77blas -latlas -lgfortran. Note that these flags are sometimes OS-dependent.

4) Use a faster version like MKL, GOTO, ... You are on your own to install it. See the doc of that software and set the Theano flags blas.ldflags correctly (for example, for MKL this might be -lmkl -lguide -lpthread or -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core -lguide -liomp5 -lmkl_mc -lpthread).

Note

Make sure your BLAS libraries are available as dynamically-loadable libraries. ATLAS is often installed only as a static library. Theano is not able to use this static library. Your ATLAS installation might need to be modified to provide dynamically loadable libraries. (On Linux this typically means a library whose name ends with .so. On Windows this will be a .dll, and on OS-X it might be either a .dylib or a .so.)

This might be just a problem with the way Theano passes compilation arguments to g++, but the problem is not fixed yet.

Note

If you have problems linking with MKL, Intel Line Advisor and the MKL User Guide can help you find the correct flags to use.

Using the GPU

The first thing you’ll need for Theano to use your GPU is Nvidia’s GPU-programming toolchain. You should install at least the CUDA driver and the CUDA Toolkit, as described here. The CUDA Toolkit installs a folder on your computer with subfolders bin, lib, include, and some more too. (Sanity check: The bin subfolder should contain an nvcc program which is the compiler for GPU code.) This folder is called the cuda root directory. You must also add the ‘lib’ subdirectory (and/or ‘lib64’ subdirectory if you have a 64-bit Linux computer) to your $LD_LIBRARY_PATH environment variable.

You must then tell Theano where the CUDA root folder is, and there are three ways to do it. Any one of them is enough.

  • Define a $CUDA_ROOT environment variable to equal the cuda root directory, as in CUDA_ROOT=/path/to/cuda/root, or
  • add a cuda.root flag to THEANO_FLAGS, as in THEANO_FLAGS='cuda.root=/path/to/cuda/root', or
  • add a [cuda] section to your .theanorc file containing the option root = /path/to/cuda/root.

Note

On Debian, you can ask the software package manager to install it for you. We have a user report that this works for Debian Wheezy (7.0). When you install it this way, you won’t always have the latest version, but we were told that it gets updated regularly. One big advantage is that it will be updated automatically. You can try the sudo apt-get install nvidia-cuda-toolkit command to install it.

Ubuntu instructions.

Once that is done, the only thing left is to change the device option to name the GPU device in your computer, and set the default floating point computations to float32. For example: THEANO_FLAGS='cuda.root=/path/to/cuda/root,device=gpu,floatX=float32'. You can also set these options in the .theanorc file’s [global] section:

[global]
device = gpu
floatX = float32

Note that:

  • If your computer has multiple GPUs and you use ‘device=gpu’, the driver selects the one to use (usually gpu0).
  • You can use the program nvida-smi to change this policy.
  • You can choose one specific GPU by specifying ‘device=gpuX’, with X the the corresponding GPU index (0, 1, 2, ...)
  • By default, when device indicates preference for GPU computations, Theano will fall back to the CPU if there is a problem with the GPU. You can use the flag ‘force_device=True’ to instead raise an error when Theano cannot use the GPU.

Once your setup is complete, head to Using the GPU to find how to verify everything is working properly.

Note

There is a compatibility issue affecting some Ubuntu 9.10 users, and probably anyone using CUDA 2.3 with gcc-4.4. Symptom: errors about “__sync_fetch_and_add” being undefined. Solution 1: make gcc-4.3 the default gcc (http://pascalg.wordpress.com/2010/01/14/cuda-on-ubuntu-9-10linux-mint-helena/) Solution 2: make another gcc (e.g. gcc-4.3) the default just for nvcc. Do this by making a directory (e.g. $HOME/.theano/nvcc-bindir) and installing two symlinks in it: one called gcc pointing to gcc-4.3 (or lower) and one called g++ pointing to g++-4.3 (or lower). Then add compiler_bindir = /path/to/nvcc-bindir to the [nvcc] section of your .theanorc (libdoc_config).

MacOS

There are various ways to install Theano dependencies on a Mac. Here we describe the process in detail with EPD, Anaconda or with MacPorts, but if you did it differently and it worked, please let us know the details on the theano-users mailing-list, so that we can add alternate instructions here.

In academia: Enthought Python Distribution (EPD)

If you are working in academia, the easiest way to install most of the dependencies is to install Enthought Python Distribution (EPD). If you are affiliated with a university (as student or employee), you can download the installer for free.

EPD installation includes in particular Python (and the development headers), numpy, scipy, nose, sphinx, easy_install, pydot (but not Graphviz, which is necessary for it to work) and the MKL implementation of blas. The Mac OS and Linux version do not include g++.

pip is not included in EPD. After the installation of EPD, you can simply install it with:

.. code-block:: bash

    $ sudo easy_install pip

Then in a terminal execute this command to install the latest Theano release:

$ sudo pip install Theano

If you want the bleeding edge version, download and install git. Then in a terminal excute this command:

$ sudo pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git

See the section install_bleeding_edge for more information on the bleading edge version.

Then you must install g++. You can do this by installing XCode. See the first bullet in the MacPorts section.

Note

If you use the trunk or version 0.6 or later of Theano, we try to automaticaly link with the EPD blas version. Due to Mac OS peculiarities, we need a user intervention to do it. We detect if the user did the modification and if not, we tell him how to do it.

Anaconda 1.5

An easy way to install most of the dependencies is to install Anaconda. There is a free version available to everybody. If you install their MKL Optimizations product (free for academic, ~30$ otherwise) Theano will also be optimized as we will reuse the faster BLAS version automatically.

Anaconda installation includes in particular Python (and the development headers), numpy, scipy, nose, sphinx, pip, and a acceptable BLAS version. The Mac OS and Linux version do not include g++.

After installing Anaconda, in a terminal execute this command to install the latest Theano release:

$ pip install Theano

To install the missing Theano optional dependency (pydot):

$ conda install pydot

If you want the bleeding edge version, download and install git. Then in a terminal excute this command:

$ sudo pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git

See the section install_bleeding_edge for more information on the bleading edge version.

Then you must install g++. You can do this by installing XCode. See the first bullet in the MacPorts section.

Note

If you use the trunk or a version after 0.6rc3 of Theano, we try to automaticaly link with the python library. Due to Mac OS peculiarities, we need a user intervention to do it. We detect if the user did the modification and if not, we tell him how to do it.

MacPorts

Using MacPorts to install all required Theano dependencies is easy, but be aware that it will take a long time (a few hours) to build and install everything.

  • MacPorts requires installing XCode first (which can be found in the Mac App Store), if you do not have it already. If you can’t install it from the App Store, look in your MacOS X installation DVD for an old version. Then update your Mac to update XCode.

  • Download and install MacPorts, then ensure its package list is up-to-date with sudo port selfupdate.

  • Then, in order to install one or more of the required libraries, use port install, e.g. as follows:

    $ sudo port install py27-numpy +atlas py27-scipy +atlas py27-pip
    

    This will install all the required Theano dependencies. gcc will be automatically installed (since it is a SciPy dependency), but be aware that it takes a long time to compile (hours)! Having NumPy and SciPy linked with ATLAS (an optimized BLAS implementation) is not mandatory, but recommended if you care about performance.

  • You might have some different versions of gcc, SciPy, NumPy, Python installed on your system, perhaps via Xcode. It is a good idea to use either the MacPorts version of everything or some other set of compatible versions (e.g. provided by Xcode or Fink). The advantages of MacPorts are the transparency with which everything can be installed and the fact that packages are updated quite frequently. The following steps describe how to make sure you are using the MacPorts version of these packages.

  • In order to use the MacPorts version of Python, you will probably need to explicitly select it with sudo port select python python27. The reason this is necessary is because you may have an Apple-provided Python (via, for example, an Xcode installation). After performing this step, you should check that the symbolic link provided by which python points to the MacPorts python. For instance, on MacOS X Lion with MacPorts 2.0.3, the output of which python is /opt/local/bin/python and this symbolic link points to /opt/local/bin/python2.7. When executing sudo port select python python27-apple (which you should not do), the link points to /usr/bin/python2.7.

  • Similarly, make sure that you are using the MacPorts-provided gcc: use sudo port select gcc to see which gcc installs you have on the system. Then execute for instance sudo port select gcc mp-gcc44 to create a symlink that points to the correct (MacPorts) gcc (version 4.4 in this case).

  • At this point, if you have not done so already, it may be a good idea to close and restart your terminal, to make sure all configuration changes are properly taken into account.

  • Afterwards, please check that the scipy module that is imported in Python is the right one (and is a recent one). For instance, import scipy followed by print scipy.__version__ and print scipy.__path__ should result in a version number of at least 0.7.0 and a path that starts with /opt/local (the path where MacPorts installs its packages). If this is not the case, then you might have some old installation of scipy in your PYTHONPATH so you should edit PYTHONPATH accordingly.

  • Please follow the same procedure with numpy.

  • This is covered in the MacPorts installation process, but make sure that your PATH environment variable contains /opt/local/bin and /opt/local/sbin before any other paths (to ensure that the Python and gcc binaries that you installed with MacPorts are visible first).

  • MacPorts does not create automatically nosetests and pip symlinks pointing to the MacPorts version, so you can add them yourself with

    $ sudo ln -s /opt/local/bin/nosetests-2.7 /opt/local/bin/nosetests
    $ sudo ln -s /opt/local/bin/pip-2.7 /opt/local/bin/pip
    
  • At this point you are ready to install Theano with

    $ sudo pip install Theano
    

    And if you are in no hurry, you can run its test-suite with

    $ python -c "import theano; theano.test()"
    

Homebrew

There are some instructions by Samuel John on how to install Theano dependencies with Homebrew instead of MacPort.

Using the GPU

You should be able to follow the Linux instructions to setup CUDA, but be aware of the following caveats:

  • If you want to compile the CUDA SDK code, you may need to temporarily revert back to Apple’s gcc (sudo port select gcc) as their Makefiles are not compatible with MacPort’s gcc.
  • If CUDA seems unable to find a CUDA-capable GPU, you may need to manually toggle your GPU on, which can be done with gfxCardStatus.

Once your setup is complete, head to Using the GPU to find how to verify everything is working properly.

Troubleshooting MacOS issues

Although the above steps should be enough, running Theano on a Mac may sometimes cause unexpected crashes, typically due to multiple versions of Python or other system libraries. If you encounter such problems, you may try the following.

  • You can ensure MacPorts shared libraries are given priority at run-time with export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH. In order to do the same at compile time, you can add to your ~/.theanorc:

    [gcc]
    cxxflags = -L/opt/local/lib
    
  • An obscure Bus error can sometimes be caused when linking Theano-generated object files against the framework library in Leopard. For this reason, we have disabled linking with -framework Python, since on most configurations this solves the Bus error problem. If this default configuration causes problems with your Python/Theano installation and you think that linking with -framework Python might help, then either set the THEANO_FLAGS environment variable with THEANO_FLAGS=cmodule.mac_framework_link or edit your ~/.theanorc to contain

    [cmodule]
    mac_framework_link=True
    
  • More generally, to investigate libraries issues, you can use the otool -L command on .so files found under your ~/.theano directory. This will list shared libraries dependencies, and may help identify incompatibilities.

Please infom us if you have trouble installing and running Theano on your Mac. We would be especially interested in dependencies that we missed listing, alternate installation steps, GPU instructions, as well as tests that fail on your platform (use the theano-users@googlegroups.com mailing list, but note that you must first register to it, by going to theano-users).

Windows

Installing Dependencies

Note

Command lines listed below are assumed to be run in a Windows prompt: click Start and type the cmd command to launch a command window.

In academia: EPD

If you are working in academia, the easiest way to install most of the dependencies is to install Enthought Python Distribution (EPD). If you are affiliated with a university (as student or employee), you can download the installation for free.

EPD installation includes in particular Python (and the development headers), numpy, scipy, nose, sphinx, easy_install, pydot (but not Graphviz, which is necessary for it to work), g++, and the MKL implementation of blas.

If you want to use the iPython shell, you should first try to import numpy in it:

C:\Users\user>ipython
[...]
In [1]: import numpy

If you see an error message telling you that DLL load failed, that is probably due to a bug in the script launching ipython. If C:\Python27 is the directory where you installed EPD, edit C:\Python27\Scripts\ipython.bat, there should be a line saying:

set path="C:\Python27";%path%

Remove the quotes around Python27, leading to:

set path=C:\Python27;%path%

Then, it should work in all new terminals.

pip is not included in EPD, but you can simply install it with:

easy_install pip

You can then proceed to the Basic user installation or the Bleeding-edge installation.

Alternative: Canopy

Another software from Enthought that installs all Theano dependencies. If you are affiliated with a university (as student or employee), you can download the installation for free.

  • Install Canopy x64, and update it to the latest version (Help / Software updates...), as older Canopy versions have trouble installing pip.
  • Then install pip from Canopy Package Manager.
  • In the Windows shell (type cmd in the Windows start menu to bring it up), type pip install theano.
  • In Canopy Package Manager, search and install packages “mingw 4.5.2” and “libpython 1.2”
  • (Needed only for Theano 0.6rc3 or earlier) The “libpython 1.2” package installs files libpython27.a and libmsvcr90.a to C:\Users\<USER>\AppData\Local\Enthought\Canopy\User\libs. Copy the two files to C:\Users\<USER>\AppData\Local\Enthought\Canopy\App\appdata\canopy-1.0.0.1160.win-x86_64libs.
  • (Needed only for Theano 0.6rc3 or earlier) Set the Theano flags blas.ldflags=-LC:\Users\<USER>\AppData\Local\Enthought\Canopy\App\appdata\canopy-1.0.0.1160.win-x86_64\Scripts -lmk2_core -lmk2_intel_thread -lmk2_rt.

Alternative: AnacondaCE

ContinuumIO is providing a free Python distribution for Windows (32-bit and 64-bit), including all dependencies of Theano. If you are not eligible for a download of EPD or Canopy (via a commercial, or free academic licence), this is the easiest way to install Theano’s dependencies. Simply download and execute the installer from AnacondaCE downlowad page, then download and execute the Windows installer for AnacondaCE.

Alternative: Python(x,y)

If you do not have a commercial licence of EPD, and are not eligible to a free academic licence, and neither Python nor MinGW is installed on your computer, you can install most dependencies of Theano with Python(x,y). It is a single installation file that contains additional packages like NumPy, SciPy, IPython, Matplotlib, MinGW, Nose, etc. Note however that there is no 64 bit version currently available. You can keep the default install options, except that the installation directory should not contain any blank space (in particular, do not install it into C:\Program Files).

Alternative: manual installation

The following instructions provide steps for manual installation of all Theano dependencies. Note that it should be possible to run Theano with Cygwin instead of MinGW, but this has not been tested yet.

  • For 32 bit MinGW: from the MinGW files, download the latest version of the Automated MinGW Installer (mingw-get-inst) and install it (you should install all optional components, except the Objective C and Ada compilers which are not needed).

  • For 64 bit MinGW (note that manual installation for 64 bit is experimental): download the latest version of MinGW-w64 from the project’s releases page, and extract it for instance to C:\mingw64. Also download MSYS from this page (although it is a 32-bit version of MSYS, this does not matter since it is only a convenience tool). Extract MSYS into the same folder, so that for instance you end up with C:\mingw64\msys. Run C:\mingw64\msys\msys.bat and in the MSYS shell, type

    sh /postinstall/pi.sh
    

    and answer the few questions so that MSYS is properly linked to your MinGW install.

  • It is recommended to set your MSYS home to be the same as your Windows home directory. This will avoid inconsistent behavior between running Theano in a Windows command prompt vs. a MSYS shell. One way to do this without setting a global Windows HOME environment variable (which may affect other programs) is to edit your msys.bat file (found e.g. under C:\MinGW\msys\1.0 or C:\mingw64\msys) and add the following line at the beginning (note that you may need to use e.g. Wordpad to edit this file, since Notepad gets confused by Unix-style line breaks):

    set HOME=%USERPROFILE%
    
  • If you do not have them already, install the latest versions of Python 2.x and corresponding NumPy then SciPy packages (simply use the executable installers). Note that there are currently no official 64 bit releases of NumPy and SciPy, but you can find unofficial builds here.

  • Ensure that the Python installation directory and its Scripts sub-directory are in your system path. This may be done by modifying the global PATH Windows environment variables, or by creating a .profile file in your MinGW home, containing a line like export PATH=$PATH:/c/Python27:/c/Python27/Scripts (note that the latter will work only when you run Theano from an MSYS shell).

  • If you are installing the 64 bit version, you will need the following hack to be able to compile Theano files with GCC (skip this step if you are using the 32 bit version). In a temporary work directory, copy python27.dll (found in C:\\Windows\\System32) as well as python27.def. Edit python27.def and replace Py_InitModule4 with Py_InitModule4_64. Then open an MSYS shell, go to this temporary directory, and run:

    dlltool --dllname python27.dll --def python27.def --output-lib libpython27.a
    

    Finally, copy the libpython27.a file that was generated into your C:\\Python27\\libs folder.

  • In order to run Theano’s test-suite, you will need nose. After unpacking its source code (you may use 7-zip), you can build and install it from within its code directory by running the following command (either from a Windows command prompot or an MSYS shell):

    python setup.py install
    

At this point, whether you installed Python(x,y) or individual components, you should have MinGW, Python, Numpy, Scipy and Nose installed.

Installing Theano

Once the dependencies are installed, you can download and install Theano. The easiest way is to install the latest released version (see Basic user installation). However, if you want to get the latest development version, or edit the code, you should follow the instructions in Bleeding-edge installation.

Windows installer for AnacondaCE

Note

This don’t work with current Anaconda. Help needed to repair this.

If you installed AnacondaCE, the simplest way to install and configure Theano is to download and execute this Windows installer for Theano on AnacondaCE for Windows.

Note

It is possible that you need to logout/login or restart the computer after installing AnacondaCE and before running Theano installer. Otherwise, sometimes the Theano installer while trying to find pip.

Note

This installer was tested on Windows 7, 64-bit edition, and AnacondaCE version 1.3.1. Please get back to us if you experience trouble with it.

This installer will:

  • Copy MinGW runtime DLLs into C:\\Anaconda\\, so they are in the PATH;
  • Call pip install theano, installing the latest released version;
  • Set up a default configuration file for Theano, theanorc_default.txt, and set it up as your .theanorc.txt if it does not exist. It contains:
[global]
openmp=False

[blas]
ldflags=

When uninstalling, it will call pip uninstall Theano, and remove the compilation cache as well as theanorc_default.txt.

Basic user installation

The easiest way to obtain the released version of Theano is from PyPI using pip by typing, in a Windows command prompt:

pip install Theano

Bleeding-edge installation

We describe here instructions to use the latest code repository version (bleeding-edge). Command lines listed below are assumed to be run in a Windows prompt (click Start and type the cmd command), and may need to be adapted if used within an MSYS Shell (not available if you only installed Python(x,y)).

  • The first option is to navigate to the Theano github page and click the ZIP button in the top-left corner to download a zip file with the latest development version. Unzip this file where you want Theano to be installed, then rename the unzipped folder to Theano.

  • The second option is to use Git, which you can get here: download the latest version of the “Full installer for official Git” from the msysgit download page. We recommend that you select the following options: “Run Git from the Windows Command Prompt” / ‘Use Git Bash only”, then “Checkout as is, commit Unix-style endings”. Navigate into the directory you want Theano to be installed in, and download it with

    git clone git://github.com/Theano/Theano.git
    
  • Add (or edit) the PYTHONPATH environment variable (into Control Panel / System / Advanced / Environment Variables), so that it contains the full installation directory of Theano. Restart a prompt to verify that it works (the example below assumes you installed Theano into your home directory):

    C:\Users\login>echo %PYTHONPATH%
    C:\Users\login\Theano
    

Configure Theano

If you installed Python through EPD, or through the installation script for Anaconda, you should be all set by now. Otherwise, whether you installed Theano through pip or git, you should follow these steps.

  • Create a new .theanorc text file (or .theanorc.txt, whichever is easier for you to create under Windows) in your user profile directory (the directory you are into when you start a new command prompt with cmd), containing the following two lines:

    [blas]
    ldflags =
    

    You do not need to do the following now, because it is not usually needed, but if later on, when running Theano, you see an error message that looks like: error: ‘assert’ was not declared in this scope then you will have to add another section:

    [gcc]
    cxxflags = -IC:\MinGW\include
    
  • You are now ready to run Theano. It will use NumPy for dot products, which is still pretty fast (see below for optional instructions on how to compile your own BLAS library). To test that Theano correctly reads your configuration file, run Python (e.g. by just typing python in a prompt) and run the following code:

    import theano
    print theano.config.blas.ldflags
    

    This should print the same content as in your config file, i.e. nothing (if your config file was not read properly, it would print ‘-lblas’, and trying to compile any Theano function would result in a compilation error due to the system being unable to find ‘blas.dll’).

Testing your installation

Currently, due to memory fragmentation issue in Windows, the test-suite breaks at some point when using theano-nose, with many error messages looking like: DLL load failed: Not enough storage is available to process this command. As a workaround, you can instead run:

theano-nose --batch

This will run tests in batches of 100, which should avoid memory errors. Note that this script calls nosetests, which may require being run from within an MSYS shell if you installed Nose manually as described above.

Note

In Theano versions <= 0.5, theano-nose was not included. If you are working with such a version, you can call this command instead:

python theano/tests/run_tests_in_batch.py

Editing code in Visual Studio

You will find a Visual Studio solution file (Theano.sln) in the root of the Theano repository. Note that this project file may not be kept up-to-date and is not officiallly supported by the core Theano developers: it is provided for convenience only. Also, be aware that it will not make Theano use Visual Studio to compile C files: it is only meant to provide an easy way to edit Theano code within the Visual Studio editor.

Compiling a faster BLAS

If you installed Python through EPD, Theano will automatically link with the MKL library included in EPD, so you should not need to compile your own BLAS.

Note

The instructions below have not been tested in a Windows 64 bit environment.

If you want a faster and/or multithreaded BLAS library, you can compile OpenBLAS (ATLAS may work too, but was not tested, and is usually reported to be slower and more difficult to compile – especially on Windows). OpenBLAS can be downloaded as a zip file from its website (we tested v0.2.6). To compile it, you will also need MSYS and wget (installation steps are described below).

If you already have a full install of MinGW, you should have MSYS included in it, and thus should be able to start a MinGW shell. If that is the case, you can skip the following MSYS installation steps. Note that these steps were written for Python(x,y), but should also work for other bundle Python distributions like EPD (changing paths accordingly, for instance in EPD 7.3.2 the MinGW folder is EPD7.3.2\EGG-INFO\mingw\usr\i686-w64-mingw32). To install MSYS on top of the MinGW installation included within Python(x,y), do as follows:

  • Download the mingw-get command-line installer binary.

  • Unpack its content into your pythonxy\mingw directory.

  • In a prompt (cmd), install MSYS with

    mingw-get install msys-base
    

    If mingw-get cannot be found automatically, just navigate first into the folder were it was extracted (it is found in the bin subfolder).

  • Edit pythonxy\mingw\msys\1.0\msys.bat (e.g. in Wordpad) and add as first line set HOME=%USERPROFILE%. Then create an easily accessible shortcut (e.g. on your desktop) to this file, run it and within the MSYS console, run the MSYS post-install script:

    /postinstall/pi.sh
    

    It will ask for your MinGW installation directory (e.g. c:/pythonxy/mingw; note the forward slashes).

Once you have a working MinGW/MSYS shell environment, you can go on as follows:

  1. Install wget by running the setup program you can download on the wget website. Note that this setup does not add wget into the system PATH, so you will need to modify the PATH environment variable accordingly (either in Windows or in a .profile startup file in your MinGW home). Once this is done, type wget --version in a MinGW shell to verify that it is working properly. Note also that if you are behind a proxy, you should set up your HTTP_PROXY environment variable, or use a custom wgetrc config file for wget to be able to download files.
  2. Unzip OpenBLAS and, in a MinGW shell, go into the corresponding directory.
  3. Compile OpenBLAS with:
quickbuild.win32 1>log.txt 2>err.txt

(use quickbuild.win64 for 64-bit Windows). Compilation can take a while, so now is a good time to take a break. When it is done, you should have libopenblas.dll in your OpenBLAS folder. If that is not the case, check the err.txt log for build errors.

  1. Make sure that libopenblas.dll is in a folder that is in your PATH.
  2. Modify your .theanorc (or .theanorc.txt) with ldflags = -LX:\\YYY\\ZZZ -lopenblas where X:\\YYY\\ZZZ is the path to the folder containing libopenblas.dll. This setting can also be changed in Python for testing purpose (in which case it will remain only for the duration of your Python session):
theano.config.blas.ldflags = "-LX:\\YYY\\YYY -lopenblas"
  1. To test the BLAS performance, you can run the script theano/misc/check_blas.py. Note that you may control the number of threads used by OpenBLAS with the OPENBLAS_NUM_THREADS environment variable (default behavior is to use all available cores). Here are some performance results on an Intel Core2 Duo 1.86 GHz, compared to using Numpy’s BLAS or the un-optimized standard BLAS (compiled manually from its source code). Note that we report here results for GotoBLAS2 which is the ancestor of OpenBLAS (this benchmark still needs to be updated with OpenBLAS results):

    • GotoBLAS2 (2 threads): 16s
    • NumPy (1 thread): 48s
    • Standard BLAS (un-optimized, 1 thread): 166s
    Conclusions:
    • The unoptimized standard BLAS is very slow and should not be used.
    • The Windows binaries of NumPy were compiled with ATLAS and are surprisingly fast.
    • GotoBLAS2 is even faster, in particular if you can use multiple cores.

Note

If you get a DLL load failed error message, it typically means that a required DLL was not found in the PATH. If it happens only when you are using OpenBLAS, it means it is either libopenblas.dll itself or one of its dependencies. In the case where it is a dependency, you can use the Dependency Walker utility to figure out which one.

Using the GPU

Currently, GPU support under Windows is still in an experimental state. The following instructions should allow you to run GPU-enabled Theano code only within a Visual Studio command prompt. Those are instructions for the 32-bit version of Python (the one that comes with Python(x,y) is 32-bit).

Blanks or non ASCII characters are not always supported in paths. Python supports them, but nvcc may not (for instance version 3.1 does not). It is thus suggested to manually define a compilation directory without such characters, by adding to your Theano configuration file:

[global]
base_compiledir=path_to_a_directory_without_such_characters

Then

  1. From the CUDA downloads page, download and install:
  1. The Developer Drivers (32-bit on 32-bit Windows, 64-bit on 64-bit Windows).
  2. The CUDA Toolkit (32-bit even if your Windows is 64-bit, as it must match your Python installation).
  3. The GPU Computing SDK (32-bit as well).
  1. Test some pre-compiled examples of the SDK.

  2. Install Visual C++ (you can find free versions by looking for “Visual Studio Express”).

  3. Follow instructions from the “CUDA Getting Started Guide” available on the NVidia website to compile CUDA code with Visual C++. If that does not work, you will probably not be able to compile GPU code with Theano.

  4. Edit your Theano configuration file to add lines like the following (make sure these paths match your own specific versions of Python and Visual Studio):

    [nvcc]
    flags=-LC:\Python26\libs
    compiler_bindir=C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin
    
  5. Start a Visual Studio command prompt (found under the “Visual Studio Tools” programs folder). In Python do: import theano.sandbox.cuda. This will compile the first CUDA file, and no error should occur.

  6. To test a simple GPU computation, first set up Theano to use the GPU by editing your configuration file:

    [global]
    device = gpu
    floatX = float32
    
Then run the theano/misc/check_blas.py test file.

You can also find additional test code and useful GPU tips on the Using the GPU page.

Generating the documentation

You can read the latest HTML documentation here. You can download the latest PDF documentation here.

We recommend you look at the documentation on the website, since it will be more current than the documentation included with the package.

If you really wish to build the documentation yourself, you will need epydoc and sphinx, as described above. Issue the following command:

python ./doc/scripts/docgen.py

Documentation is built into html/. The PDF of the documentation is html/theano.pdf.