
.. _install:


Installing Theano
=================

.. note::
    If you are a member of LISA Labo, have a look at :ref:`lisa_labo` 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. 32-bit 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 <http://numpy.scipy.org/>`_ >= 1.5.0
        Earlier versions could work, but we don't test it.

    `SciPy <http://scipy.org>`_
        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).

.. _BLAS: http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms
.. _Accelerate framework: http://developer.apple.com/performance/accelerateframework.html
.. _Python: http://www.python.org/

The following libraries and software are optional:

    `nose <http://somethingaboutorange.com/mrl/projects/nose/>`_
        Recommended, to run Theano's test-suite.

    `Sphinx <http://sphinx.pocoo.org/>`_ >= 0.5.1, `pygments <http://pygments.org/>`_
        For building the documentation. LaTeX_ and dvipng_ are also necessary
        for math to show up as images.

    `Git <http://git-scm.com>`_
        To download bleeding-edge versions of Theano.

    `pydot <https://code.google.com/p/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.

.. _LaTeX: http://www.latex-project.org/
.. _dvipng: http://savannah.nongnu.org/projects/dvipng/
.. _NVIDIA CUDA drivers and SDK: http://developer.nvidia.com/object/gpucomputing.html

Linux
-----

CentOS 6
~~~~~~~~

:ref:`install_centos6` 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.

.. Cent OS 6

Ubuntu
~~~~~~

:ref:`install_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
<http://groups.google.com/d/msg/theano-dev/-8WCMn2FMR0/bJPasoZXaqoJ>`_,
focusing on how to install the appropriate dependencies.

Nicolas Pinto provides `ebuild scripts <https://github.com/npinto/sekyfsr-gentoo-overlay/tree/master/sci-libs/Theano>`_.

Alternative installation on Mandriva 2010.2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. _Mandriva: http://mib.pianetalinux.org/mib/quick/basic-rpms/mib-rpms/975-theano-031


.. _linux_basic:

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

.. code-block:: bash

    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 to an alternate prefix using

.. code-block:: bash

    pip install Theano --install-option='--prefix=~/.local'

e.g. using ``--install-option='--prefix=~/.local'`` on Python 2.4 would
install Theano into ``.local/lib/python2.4/site-packages`` inside your home
directory on Mac OS X or Unix/Linux (this ``site-packages`` directory must be
listed in your ``PYTHONPATH`` environment variable; for Python 2.6 and later,
``~/.local`` is
automatically searched and does *not* need to be explicitly included in
``PYTHONPATH``, see :ref:`config_pythonpath` for instructions).
You can change ``~/.local``, but you need to change your ``PYTHONPATH`` as said above.

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_ as
    a long-standing bug in ``easy_install`` prevents ``theano.test()`` from
    running the Theano test suite; ``pip`` offers many other 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``.

.. _distribute: http://packages.python.org/distribute/
.. _setuptools: http://pypi.python.org/pypi/setuptools
.. _easy_install: http://packages.python.org/distribute/easy_install.html
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _virtualenv documentation: http://virtualenv.openplans.org/
.. _pip: http://pypi.python.org/pypi/pip

.. _updating:

Updating Theano
~~~~~~~~~~~~~~~

The following command will update only Theano:

.. code-block:: bash

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

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

.. code-block:: bash

    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:

.. code-block:: bash

    theano-cache clear

.. _install_bleeding_edge:

Bleeding-edge install instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Master Tests Status:

.. image:: https://secure.travis-ci.org/Theano/Theano.png?branch=master
    :target: http://travis-ci.org/Theano/Theano/builds

If you are a developer of Theano, then check out the :ref:`dev_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.

.. code-block:: bash

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

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

.. code-block:: bash

    pip install --upgrade --no-deps git+git://github.com/Theano/Theano.git --install-option='--prefix=~/.local'

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 <http://git-scm.com>`__:

.. code-block:: bash

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

.. code-block:: bash

    cd Theano
    python setup.py develop

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

.. code-block:: bash

    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.

.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _virtualenv documentation: http://virtualenv.openplans.org/
.. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper/

.. _config_pythonpath:

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:

.. code-block:: bash

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

In csh:

.. code-block:: 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:

.. code-block:: bash

    git pull

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


.. _testing_installation:

Testing your installation
~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: python

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

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

.. code-block:: bash

    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 :attr:`~config.device`
    set to ``cpu`` (default). If you need to change this value,
    you can do that by setting the :envvar:`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 :attr:`~config.init_gpu_device`.
    For instance: ``THEANO_FLAGS=device=cpu,init_gpu_device=gpu1``.

    See :ref:`libdoc_config` 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`` (:ref:`libdoc_config`). 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 :envvar:`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:

.. code-block:: cfg

    # 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 :ref:`libdoc_config`.

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.

.. _gpu_linux:

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 <http://www.nvidia.com/object/cuda_get.html>`_.  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 :envvar:`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``.

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:

     .. code-block:: cfg

        [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 :ref:`using_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`).


.. _Graphviz: http://www.graphviz.org/Download_windows.php

MacOS
-----

There are various ways to install Theano dependencies on a Mac.
Here we describe the process in detail with EPD 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) <http://enthought.com/products/epd.php>`_.
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:

    .. code-block:: bash

        $ sudo pip install Theano

If you want the bleeding edge version, `download
and install git <http://git-scm.com/downloads>`_. Then in a
terminal excute this command:

.. code-block:: bash

    $ 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 :ref:`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.

.. _macports:

MacPorts
~~~~~~~~

Using `MacPorts <http://www.macports.org/>`__ 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 <http://www.macports.org/>`__, 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:

    .. code-block:: bash

        $ 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

    .. code-block:: bash

        $ 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

    .. code-block:: bash

        $ sudo pip install Theano

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

    .. code-block:: bash

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

Homebrew
~~~~~~~~

There are some `instructions
<https://github.com/samueljohn/homebrew-python>`__ by Samuel John on how to install
Theano dependencies with Homebrew instead of MacPort.


.. _gpu_macos:

Using the GPU
~~~~~~~~~~~~~

You should be able to follow the :ref:`Linux <gpu_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 <http://codykrieger.com/gfxCardStatus>`__.

Once your setup is complete, head to :ref:`using_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``:

    .. code-block:: cfg

      [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 :envvar:`THEANO_FLAGS` environment variable with
  ``THEANO_FLAGS=cmodule.mac_framework_link`` or edit your ``~/.theanorc`` to
  contain

    .. code-block:: cfg

      [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) <http://enthought.com/products/epd.php>`_.
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 :ref:`windows_basic` or the :ref:`windows_bleeding_edge`.


Alternative: Anaconda 0.8.3 (Linux VM on Windows)
#################################################

ContinuumIO_ was providing a free VM with Theano installed. Now they
provide a new installation system that installs itself on Windows.
Since we lack time to update this part of the documentation, it has been
removed for now. Check back later!

.. _ContinuumIO: http://continuum.io

Alternative: Python(x,y)
########################

If you are not eligible to a free download of EPD, and
neither Python nor MinGW is installed on your computer, the easiest way to
install most dependencies is to install
`Python(x,y) <http://www.pythonxy.com>`__.
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 <http://www.cygwin.com/>`__ instead of
MinGW, but this has not been tested yet.

- For 32 bit MinGW: from `the MinGW files <http://sourceforge.net/projects/mingw/files/>`__,
  download the latest version of the ``Automated MinGW Installer``
  (``mingw-get-inst``) and install it with all optional components (although
  you probably do not need them all: if you feel like figuring out exactly
  which ones are required, let us know!).

- 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 <http://sourceforge.net/projects/mingw-w64/files/>`__, and extract
  it for instance to ``C:\mingw64``. Also download MSYS from
  `this page <http://sourceforge.net/projects/mingw-w64/files/External%20binary%20packages%20%28Win64%20hosted%29/MSYS%20%2832-bit%29/>`__
  (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

   .. code-block:: bash

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

    .. code-block:: bash

        set HOME=%USERPROFILE%

- If you do not have them already, install the latest versions of
  `Python 2.x <http://www.python.org/download/windows>`__ and
  corresponding `NumPy <http://sourceforge.net/projects/numpy/files/>`__
  then `SciPy <http://sourceforge.net/projects/scipy/files/>`__
  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 <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`__.

- 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 <http://wiki.cython.org/InstallingOnWindows?action=AttachFile&do=get&target=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:

    .. code-block:: bash

        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
  <http://somethingaboutorange.com/mrl/projects/nose>`__.
  After unpacking its source code (you may use `7-zip
  <http://www.7-zip.org/>`__), 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):

    .. code-block:: bash

        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 :ref:`windows_basic`).  However, if you want to get the latest
development version, or edit the code, you should follow the
instructions in :ref:`windows_bleeding_edge`.

.. _windows_basic:

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:

.. code-block:: bash

    pip install Theano


.. _windows_bleeding_edge:

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 <http://github.com/Theano/Theano>`__ 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 <http://git-scm.com/download>`__: 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

    .. code-block:: bash

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

    .. code-block:: none

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

Configure Theano
################

If you installed Python through EPD, 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:

    .. code-block:: cfg

      [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:

    .. code-block:: cfg

      [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:

  .. code-block:: python

      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:

    .. code-block:: bash

        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:

    .. code-block:: bash

        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::

   GotoBLAS is no longer maintained and has been released under the BSD
   license. `OpenBLAS
   <https://github.com/xianyi/OpenBLAS>`_ is a new project that
   continues GotoBLAS: it has a better installation process and implements
   additional functions (not currently used by Theano).
   We did not try OpenBLAS on Windows. When installed, you probably need to
   use this Theano flags: ``theano.config.blas.ldflags = "-lopenblas"``

.. 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 GotoBLAS2 (ATLAS may work too, but was not tested, and is
usually reported to be slower and more difficult to compile -- especially
on Windows).
GotoBLAS2 can be downloaded
`here <http://www.tacc.utexas.edu/tacc-projects/gotoblas2>`__
(we tested v1.13).
To compile it, you will also need MSYS and Perl (installation steps are
described below).
The GotoBLAS makefiles actually expect a full UNIX environment (like
Cygwin) but the BLAS compilation seems to work with only MSYS and Perl
(LAPACK compilation fails, but Theano does not need it).

If you installed MinGW manually as described above, you should already
have MSYS included in your MinGW install, and should be able to start a
shell (Start / MinGW / MinGW Shell), in which case you can skip the MSYS
installation.
If instead you installed Python(x,y), you will need to install MSYS on
top of the MinGW installation included within Python(x,y), as follows:

- Download the `mingw-get command-line installer binary
  <http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/mingw-get/>`_.

- Unpack it into your ``pythonxy\mingw`` directory.

- In a prompt (``cmd``), install MSYS with

    .. code-block:: bash

        mingw-get install msys-base

- 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:

    .. code-block:: bash

        /postinstall/pi.sh

  It will ask for your MinGW installation directory (e.g.
  ``c:/pythonxy/mingw``).

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

  a) Download `ActivePerl <http://www.activestate.com/activeperl/downloads>`_ and
     install it (other Perl interpreters should also work, but were not
     tested). In a MSYS shell, type ``perl --version`` just to make sure the Perl
     executable is found automatically. If this is not the case, you may need to
     restart your MSYS shell, or even restart your computer if that is not enough.

  b) Unpack GotoBLAS2, either using `7-zip <http://www.7-zip.org/>`__ or in
     a shell with:

    .. code-block:: bash

        tar zxvf /path/to/GotoBLAS2-1.13.tar.gz

  c) In a MSYS shell, go into the GotoBLAS2 directory that was unpacked.

  d) Compile GotoBLAS2 with:

    .. code-block:: bash

      quickbuild.win32 1>log.txt 2>err.txt

    Compilation should take a few minutes. Afterwards, you will probably
    find many error messages in err.txt, but there should be an ``exports``
    folder containing in particular ``libgoto2.dll``.

  e) Copy ``libgoto2.dll`` from the ``exports`` folder to both your ``bin`` and
     ``lib`` subdirectories of your MinGW installation (which may be under
     ``pythonxy\mingw`` if you used Python(x,y)).

  f) Modify your .theanorc (or .theanorc.txt) with ``ldflags = -lgoto2``.
     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):

    .. code-block:: python

        theano.config.blas.ldflags = "-lgoto2"

  g) 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 GotoBLAS2 with
     the ``GOTO_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):

         * 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.

.. _gpu_windows:

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:

    .. code-block:: cfg

      [global]
      base_compiledir=path_to_a_directory_without_such_characters

Then

  1) From the CUDA downloads page, download and install:

    a. The Developer Drivers (32-bit on 32-bit Windows, 64-bit on 64-bit
       Windows).

    b. The CUDA Toolkit (32-bit even if your Windows is 64-bit, as it must
       match your Python installation).

    c. The GPU Computing SDK (32-bit as well).

  2) Test some pre-compiled examples of the SDK.

  3) Install Visual C++ (you can find free versions by looking for "Visual
     Studio Express").

  4) 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.

  5) 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):

     .. code-block:: cfg

        [nvcc]
        flags=-LC:\Python26\libs
        compiler_bindir=C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin

  6) 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.

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

     .. code-block:: cfg

        [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
:ref:`using_gpu` page.


Generating the documentation
----------------------------

You can read the latest HTML documentation `here
<http://deeplearning.net/software/theano>`__.
You can download the latest PDF documentation `here
<http://deeplearning.net/software/theano/theano.pdf>`__.

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``.


.. _theano-users: http://groups.google.com/group/theano-users?pli=1
.. _theano-dev: http://groups.google.com/group/theano-dev?pli=1
