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.6
- The development package (
python-dev
orpython-devel
on most Linux distributions) is recommended (see just below). Python 2.4 was supported up to and including the release 0.6.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 (thescipy.csc_matrix
version ofdot()
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 on NVIDIA gpus
- libgpuarray
Required for GPU/CPU code generation on CUDA and OpenCL devices (see: GpuArray Backend.)
note: OpenCL support is still minimal for now.
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:

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 toTHEANO_FLAGS
, as inTHEANO_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.
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 bywhich python
points to the MacPorts python. For instance, on MacOS X Lion with MacPorts 2.0.3, the output ofwhich python
is/opt/local/bin/python
and this symbolic link points to/opt/local/bin/python2.7
. When executingsudo 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 instancesudo 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 byprint scipy.__version__
andprint 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 ofscipy
in yourPYTHONPATH
so you should editPYTHONPATH
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
andpip
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 theframework
library in Leopard. For this reason, we have disabled linking with-framework Python
, since on most configurations this solves theBus 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 theTHEANO_FLAGS
environment variable withTHEANO_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 withC:\mingw64\msys
. RunC:\mingw64\msys\msys.bat
and in the MSYS shell, typesh /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 yourmsys.bat
file (found e.g. underC:\MinGW\msys\1.0
orC:\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 globalPATH
Windows environment variables, or by creating a.profile
file in your MinGW home, containing a line likeexport 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 inC:\\Windows\\System32
) as well as python27.def. Editpython27.def
and replacePy_InitModule4
withPy_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 thePATH
; - 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 toTheano
.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 withgit 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 withcmd
), 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 withmingw-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 thebin
subfolder).Edit
pythonxy\mingw\msys\1.0\msys.bat
(e.g. in Wordpad) and add as first lineset 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:
- Install
wget
by running the setup program you can download on the wget website. Note that this setup does not addwget
into the system PATH, so you will need to modify thePATH
environment variable accordingly (either in Windows or in a.profile
startup file in your MinGW home). Once this is done, typewget --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 yourHTTP_PROXY
environment variable, or use a customwgetrc
config file for wget to be able to download files.- Unzip OpenBLAS and, in a MinGW shell, go into the corresponding directory.
- 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 havelibopenblas.dll
in your OpenBLAS folder. If that is not the case, check theerr.txt
log for build errors.
- Make sure that
libopenblas.dll
is in a folder that is in yourPATH
.- Modify your .theanorc (or .theanorc.txt) with
ldflags = -LX:\\YYY\\ZZZ -lopenblas
whereX:\\YYY\\ZZZ
is the path to the folder containinglibopenblas.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"
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 theOPENBLAS_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
- From the CUDA downloads page, download and install:
- The Developer Drivers (32-bit on 32-bit Windows, 64-bit on 64-bit Windows).
- The CUDA Toolkit (32-bit even if your Windows is 64-bit, as it must match your Python installation).
- The GPU Computing SDK (32-bit as well).
Test some pre-compiled examples of the SDK.
Install Visual C++ (you can find free versions by looking for “Visual Studio Express”).
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.
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\binStart 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.To test a simple GPU computation, first set up Theano to use the GPU by editing your configuration file:
[global] device = gpu floatX = float32Then run thetheano/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
.