Installing Theano

Warning

If you want to install the bleeding-edge or development version of Theanofrom GitHub, please make sure you are reading the latest version of thispage.

Requirements

In order to use Theano, the following libraries and software will needto be installed (MacOS and Windows users should refer to platform-specificinstructions 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 >= 2.6 or Python 3 >= 3.3
The development package (python-dev or python-devel on most Linux distributions) is recommended (see just below). Python 2.4 was supported up to and including the release 0.6. Python 3 is supported past the 3.3 release.
g++ (Linux and Windows), clang (macOS), python-dev (All platforms)
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.7.1
Earlier versions could work, but we don’t test it.
SciPy >= 0.11
Only currently required for sparse matrix and special functions support, but highly recommended. SciPy >=0.8 could work, but earlier versions have known bugs with sparse matrices.
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 >= 1.3.0 and nose-parameterized >= 0.5.0
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.
graphiz and either pydot-ng or pydot
To be able to make picture of Theano computation graph. pydot-ng is a pydot compatible replacement that support newer Python.
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 CentOS6, written by the Theano developers. It covers how to install Theano (forCPU-based computation only) with the distribution-packaged ATLAS, a free fastimplementation of BLAS.

Ubuntu

Easy Installation of an Optimized Theano on Current Ubuntu provides instructions on how to install Theanoon Ubuntu. It covers how to install Theano with thedistribution-packaged OpenBlas or ATLAS. Both are free fastimplementation 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.

AWS Marketplace with Bitfusion AMI

AWS EC2 AMI pre-installed with Nvidia drivers, CUDA, cuDNN, Theano, Keras, Lasagne, Python 2, Python 3, PyCuda, Scikit-Learn, Pandas, Enum34, iPython, and Jupyter. Note, as always there is no charge for Theano and other open software, however there is a charge for AWS hosting + Bitfusion.

Launch an instance from the AWS Marketplace.

Docker

Builds of Theano are available as Dockerimages: Theano Docker (CPU) orTheano Docker (CUDA). Theseare updated on a weekly basis with bleeding-edge builds of Theano.Examples of running bash in a Docker container are as follows:

  1. sudo docker run -it kaixhin/theano
  2. sudo nvidia-docker run -it kaixhin/cuda-theano:7.0

For a guide to Docker, see the official docs.CUDA support requires NVIDIA Docker.For more details on how to use the Theano Docker images,consult the source project.

Basic user install instructions

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

  1. pip install Theano

This should work under Python 2 or Python 3. To test, run

  1. nosetests theano

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

  1. pip install Theano --user

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

Note

Theano can be installed with easy_install, however we recommend pip.pip offers many benefits overeasy_install such as more intelligent dependency management, bettererror messages and a pip uninstall command for easily removingpackages.

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

Updating Theano

The following command will update only Theano:

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

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

  1. sudo pip install --upgrade theano

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

  1. theano-cache clear

Bleeding-edge install instructions

Master Tests Status: Installing Theano - 图1 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 forthis 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.

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

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

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

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

  1. 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):

  1. cd Theano
  2. python setup.py develop

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

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

  1. 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 prefixspecified 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 isolatedsite-packages is to use virtualenv; see the virtualenv documentationfor details. If you find yourself using virtualenv frequently you may find thevirtualenvwrapper package useful for switching between them.

Configuring PYTHONPATH

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

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

In csh:

  1. setenv PYTHONPATH <new location to add>:$PYTHONPATH

To make this change stick you will usually need to add the above command toyour 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:

  1. git pull

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

Specific git commit

You can install a specific git commit by using the bleeding edgeinstruction and adding @COMMIT_ID to the pip command like:

  1. pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git@07e9332a0932e90c47ed2a70fc3c7f8a55d2aa23

Testing your installation

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

  1. import theano
  2. theano.test()

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

  1. 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 addTheano/bin to your PATH environment variable.

Note

In Theano versions <= 0.5, theano-nose was not included. If youare working with such a version, you can call nosetests insteadof theano-nose. In that case, some tests will fail by raisingthe 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 deviceset 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 notthe 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 theseconfiguration options.

All tests should pass (skipped tests and known failures are normal). Ifsome test fails on your machine, you are encouraged to tell us what wentwrong 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 Theanoflags blas.ldflags (config – Theano Configuration). The default is to use the BLASinstallation information in NumPy, accessible vianumpy.distutils.config.show(). You can tell theano to use a differentversion of BLAS, in case you did not compile NumPy with a fast BLAS or if NumPywas compiled with a static library of BLAS (the latter is not supported inTheano).

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

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

  1. # other stuff can go here
  2. [blas]
  3. ldflags = -lf77blas -latlas -lgfortran #put your flags here
  4.  
  5. # other stuff can go here

For more information on the formatting of ~/.theanorc and theconfiguration 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 sameBLAS against which NumPy was built. This does not work in the case NumPy wascompiled with a static library (e.g. ATLAS is compiled by default only as astatic library).

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

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 infedora you can do sudo yum install blas blas-devel. Under Ubuntu/Debiansudo apt-get install libblas-dev. Then use the Theano flagsblas.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 functionsthat we use.

3) Install the ATLAS library. ATLAS is an open source optimized version ofBLAS. You can install a precompiled version on most OSes, but if you’re willingto invest the time, you can compile it to have a faster version (we have seenspeed-ups of up to 3x, especially on more recent computers, against theprecompiled one). On Fedora, sudo yum install atlas-devel. Under Ubuntu,sudo apt-get install libatlas-base-dev libatlas-base orlibatlas3gf-sse2 if your CPU supports SSE2 instructions. Then set theTheano flags blas.ldflags to -lf77blas -latlas -lgfortran. Note thatthese 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.ldflagscorrectly (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 BLASlibraries are available as dynamically-loadable libraries.ATLAS is often installed only as a static library. Theano is not able touse this static library. Your ATLAS installation might need to be modifiedto provide dynamically loadable libraries. (On Linux thistypically means a library whose name ends with .so. On Windows this will bea .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 compilationarguments to g++, but the problem is not fixed yet.

Note

If you have problems linking with MKL, Intel Line Advisorand the MKL User Guidecan 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’sGPU-programming toolchain. You should install at least the CUDA driver and the CUDA Toolkit, asdescribed here. The CUDAToolkit 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 _cudaroot directory.You must also add the ‘lib’ subdirectory (and/or ‘lib64’ subdirectory if you have a 64-bit Linuxcomputer) to your $LD_LIBRARY_PATH environment variable.

You must then tell Theano where the CUDA root folder is, and there are three waysto 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 itfor 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 thelatest version, but we were told that it gets updatedregularly. One big advantage is that it will be updatedautomatically. 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 yourcomputer, 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:

  1. [global]
  2. device = gpu
  3. 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 verifyeverything is working properly.

Mac OS

There are various ways to install Theano dependencies on a Mac. Herewe describe the process in detail with Canopy, Anaconda, Homebrew orMacPorts but if you did it differently and it worked, please let usknow the details on the theano-users mailing-list, so that we canadd alternate instructions here.

In academia: Enthought Canopy

If you are working in academia, the easiest way to install most of thedependencies is to installCanopy.If you are affiliated with a university (as student or employee), youcan download the installer for free.

The Canopy installation includes in particular Python (and thedevelopment headers), NumPy, SciPy, nose, sphinx, pip, pydot(but not Graphviz, which is necessary for it to work) and the MKLimplementation of blas.

To install the latest Theano release execute this in a terminal:

  1. $ pip install Theano

If you want the bleeding edge version execute this command instead:

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

See the section install_bleeding_edge for moreinformation on the bleeding edge version.

Then you must install the compiler. See Installing the compiler below.

Note

If you use version 0.6 or later of Theano, we try to automaticallylink with the Canopy blas version. Due to Mac OS peculiarities,this requires user intervention. We detect if the manipulation wasdone or not and give an error message explaining what to do in caseit hasn’t been done.

Anaconda

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

The Anaconda installation includes in particular Python (and thedevelopment headers), NumPy, SciPy, nose, sphinx, pip, and aacceptable BLAS version.

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

  1. $ pip install Theano

To install the missing Theano optional dependency (pydot):

  1. $ conda install pydot-ng

If you want the bleeding edge version instead execute this command:

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

See the section install_bleeding_edge for moreinformation on the bleeding edge version.

Then you must install the compiler. See Installing the compiler below.

Note

If you use version 0.6 or later of Theano, we try to automaticallylink with the python library. Due to Mac OS peculiarities, thisrequires user intervention. We detect if the user did themodification and if not, we tell him how to do it.

Installing the compiler

Theano officially supports only clang on OS X. This can be installedby getting XCode from the App Store and running it once to install thecommand-line tools.

If you still want to use g++ you can do so by setting its full path inthe theano config flag gxx. Note that any bug reports on Mac usingg++ will be ignored unless it can be reproduced with clang.

Homebrew

Install python with homebrew:

  1. $ brew install python # or python3 if you prefer

This will install pip. Then use pip to install numpy, scipy:

  1. $ pip install numpy scipy

If you want to use openblas instead of Accelerate, you have to installnumpy and scipy with hombrew:

  1. $ brew tap homebrew/python
  2. $ brew install numpy --with-openblas
  3. $ brew install scipy --with-openblas

Then install theano as usual:

  1. $ pip install Theano --user

Or for the bleeding-edge version:

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

MacPorts

Using MacPorts to install all requiredTheano 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 theMac App Store), if you do not have it already.If you can’t install it from the App Store, look in your MacOS X installationDVD for an old version. Then update your Mac to update XCode.

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

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

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

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

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

  • In order to use the MacPorts version of Python, you will probablyneed to explicitly select it with sudo port select python python27. Thereason this is necessary is because you may have an Apple-provided Python(via, for example, an Xcode installation). After performing this step, youshould check that the symbolic link provided by which python points tothe 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 symboliclink points to /opt/local/bin/python2.7. When executing sudo port select python python27-apple (which you should not do), the linkpoints 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 thesystem. Then execute for instance sudo port select gcc mp-gcc44to create a symlink that points to the correct (MacPorts) gcc (version 4.4in this case).

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

  • Afterwards, please check that the scipy module that is imported inPython 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 startswith /opt/local (the path where MacPorts installs its packages). If thisis not the case, then you might have some old installation of scipy in yourPYTHONPATH so you should edit PYTHONPATH accordingly.

  • Please follow the same procedure with numpy.

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

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

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

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

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

Using the GPU

You should be able to follow the Linux instructions tosetup 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 verifyeverything is working properly.

Troubleshooting MacOS issues

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

  • You can ensure MacPorts shared libraries are given priority at run-timewith export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH. In orderto do the same at compile time, you can add to your ~/.theanorc:
  1. [gcc]
  2. cxxflags = -L/opt/local/lib
  • An obscure Bus error can sometimes be caused when linkingTheano-generated object files against the framework library in Leopard.For this reason, we have disabled linking with -framework Python, since onmost configurations this solves the Bus error problem. If this defaultconfiguration causes problems with your Python/Theano installation and you thinkthat linking with -framework Python might help, then either setthe THEANO_FLAGS environment variable withTHEANO_FLAGS=cmodule.mac_framework_link or edit your ~/.theanorc tocontain
  1. [cmodule]
  2. mac_framework_link=True
  • More generally, to investigate libraries issues, you can use the otool -Lcommand on .so files found under your ~/.theano directory. This willlist shared libraries dependencies, and may help identify incompatibilities.

Please inform 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 onyour platform (use the theano-users@googlegroups.com mailing list, butnote that you must first register to it, by going to theano-users).

Windows

Installation of Theano on Windows provides step-by-step instructions on how to install Theano on 32- or 64-bit Windows systems, using freely availabletools and compilers.

Editing code in Visual Studio

You will find a Visual Studio solution file (Theano.sln) in the root ofthe Theano repository. Note that this project file may not be kept up-to-dateand is not officially supported by the core Theano developers: it is providedfor convenience only.Also, be aware that it will not make Theano use Visual Studio to compile Cfiles: it is only meant to provide an easy way to edit Theano code withinthe Visual Studio editor.

Windows Installation References

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 itwill be more current than the documentation included with the package.

If you really wish to build the documentation yourself, you will needsphinx, as described above. Issue the following command:

  1. python ./doc/scripts/docgen.py

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