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

    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
        Including the development package (``python-dev`` or ``python-devel``
	on most Linux distributions).

    ``g++``, ``python-dev``
	Not technically required but *highly* recommended, in order to compile
	generated C code. Theano `can` fall back on a NumPy-based execution
	model, but a C compiler allows for vastly faster execution.

    `NumPy <http://numpy.scipy.org/>`_ >= 1.3.0
        Earlier versions have memory leaks.

    `SciPy <http://scipy.org>`_
	Only currently required for sparse matrix and special functions
	support, but *highly* recommended. We recommend SciPy
	>=0.7 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).

    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.
    `Mercurial <http://mercurial.selenic.com/>`_
        To download bleeding-edge versions of Theano.
    `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

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=YOURPREFIX'

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

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

.. _install_bleeding_edge:

Bleeding-edge (developer) install instructions
----------------------------------------------

If you are a developer of Theano, then check out the :ref:`dev_start_guide`.

The following are general instructions that will set you up with the
bleeding-edge version of Theano. First, get the code using `Mercurial
<http://mercurial.selenic.com/>`__:

.. code-block:: bash

    hg clone http://hg.assembla.com/theano Theano

From here, the easiest way to get started is

.. 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 Mercurial). Using ``develop`` mode is
preferable to ``install`` as any modifications you make in the checkout
directory (or changes you pull with Mercurial) 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=YOURPREFIX

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

To modify the environment variable ``PYTHONPATH`` 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'll usually need to add the command to one or
more of your shell's startup scripts, i.e. ``~/.bashrc`` or ``~/.cshrc``.
Consult your shell's documentation for details.

Testing your installation
---------------------------

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

.. code-block:: python

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

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

.. code-block:: bash

    nosetests

``THEANO_FLAGS`` is an environment variable that define Theano flags
(:ref:`libdoc_config`).  For Windows users, you can remove it or see the
documentation to know how to configure them differently.

All tests should pass except the test marked as ``KnownFailureTest``. If some
test fails on your machine, you are encouraged to tell us what went wrong on
the ``theano-users@googlegroups.com`` mailing list.

.. note::

    `warn.ignore_bug_before=all` removes warnings that you don't need to see
    here.  It is also recommended for a new user to set this flag to a
    different value in their ``.theanorc`` file.  See
    :attr:`config.warn.ignore_bug_before` for more details.

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 didn't 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
environmental 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:

.. 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 doesn't 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) doesn't 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``. Not 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.  ATLAS might need to be reinstalled or upgraded or
    something 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 gcc, but the problem is not fixed yet.


Updating
-------------


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

.. code-block:: bash

    hg pull -u

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

Mac
---

- If the above required libraries are not already installed on your Mac, one option is first, to
  install `MacPorts <http://www.macports.org/>`__.

- 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 gcc44 py25-scipy mercurial python_select

    This will install all the required Theano dependencies.  Note that
    compiling gcc takes significant time (hours)! SciPy depends on ATLAS (a
    good BLAS implementation) and NumPy, so these will be installed for you automatically.

- You might have some old 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
  (provided by Fink, or by Xcode). The advantages of MacPorts are the
  transparency with which everything can be installed and the fact that
  packages are updated quite frequently.

- In order to use the MacPorts version of python, you might
  need to explicitly select it with ``sudo python_select python25``. The
  reason this is necessary is because you might 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 Snow Leopard with the latest MacPorts, 
  the output of ``which python`` is ``/opt/local/bin/python`` and this symbolic
  link points to ``/opt/local/bin/python2.5``. When executing ``sudo
  python_select python26-apple`` (which you should **not** do), the link
  points to ``/usr/bin/python2.6``.

- Once this is fixed, 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``.

- Put ``export PYTHONPATH=/opt/local/lib/python2.5/site-packages:$PYTHONPATH``
  in your ``.bashrc`` in order to include your MacPorts Python packages 
  (NumPy, SciPy) in Python's path.

- Make sure that the gcc version that you have installed on your system is
  up-to-date (at the very least 3.4, but 4.x is better). If you have an old
  version of Xcode lying around, chances are that your gcc install is old. You
  should also check  ``which gcc``: if it says  ``/usr/bin/gcc`` then you
  should install gcc_select from MacPorts (``sudo port install gcc_select``)
  and use the MacPorts-provided gcc. Use ``gcc_select -l`` to see which gcc
  installs you have on the system. Then execute ``sudo gcc_select mp-gcc44``
  to create a symlink that points to the correct (MacPorts) gcc (version 4.4
  in this case).

- This is covered in the MacPorts installation process, but make sure that
  your ``PATH`` environmental 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).

- Likewise, you need to
  ``export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH`` if this is not
  the case already (so that we link to the correct libraries). You may also
  need to add

    .. code-block:: cfg

      [gcc]
      cxxflags = -L/opt/local/lib

  to ``~/.theanorc``.

- An obscure ``Bus error`` can sometimes be caused when linking
  Theano-generated object files against the ``framework`` library in Leopard.
  For this reason, we've 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
  ``THEANO_FLAGS=cmodule.mac_framework_link`` or edit your ``~/.theanorc`` to
  contain

    .. code-block:: cfg

      [cmodule]
      mac_framework_link=True

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, 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 V1 (Installing from Scratch)
------------------------------------

- Install `Python(x,y) <http://www.pythonxy.com>`_ in a directory without blank
  spaces in the name (in particular not into ``C:\Program Files``).
  It is a single installation
  file that contains additional packages like NumPy, SciPy, IPython, Matplotlib,
  MinGW, Nose, etc. Note that this implies you do not already have a Python
  installation (if you do have one, then you will need to either remove it first,
  or install those additional packages manually as described in the V2 instructions).
  You can keep the default install options (except for the installation directory).

- Install Mercurial. You can download it
  `here <http://mercurial.selenic.com/downloads>`_. You may get either the command
  line Windows version or the TortoiseHG GUI version: it does not matter as
  far as installing Theano is concerned.

- Start a shell (hit the Start button and run the ``cmd`` command) and navigate to
  the directory where you want to install Theano (it is ok to just stay in the
  default directory, which should be your user profile directory). Then download
  Theano with:

    .. code-block:: bash

        hg clone http://hg.assembla.com/theano Theano

- 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 shell (``cmd``) to verify
  that it works:

    .. code-block:: none

        C:\Users\login>echo %PYTHONPATH%
        C:\Users\login\Theano
        
- Create a new ``.theanorc`` text file (or ``.theanorc.txt``, which is easier
  to create under Windows) in your user profile directory, containing the following
  two lines:
 
    .. code-block:: cfg

      [blas]
      ldflags =

- 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 shell) 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').

Windows: Using a Faster BLAS
----------------------------

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/downloads>`_
after registering on the website (we tested v1.13).
To compile it, you will also need to install MSYS and Perl,
as 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).

  a) Download the mingw-get command-line installer from the
     `MinGW files <http://sourceforge.net/projects/mingw/>`_ (click
     "View all files", and make sure you do not mix it up with
     mingw-get-inst).

  b) Unpack it into your ``pythonxy\mingw`` directory.

  c) On the command-line, install MSYS with

    .. code-block:: bash
    
        mingw-get install msys-base

  d) Create an easily accessible shortcut (e.g. on your desktop) to
     ``pythonxy\mingw\msys\1.0\msys.bat``. 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``).

  e) Download `ActivePerl <http://www.activestate.com/activeperl/downloads>`_ and
     install it (other Perl interpreters should also work).
    
  f) Unpack GotoBLAS2, either using `7-zip <http://www.7-zip.org/>`_ or in
     MSYS with:

    .. code-block:: bash

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

  g) In MSYS, go into the GotoBLAS2 directory that was unpacked.

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

  i) Copy ``libgoto2.dll`` from the ``exports`` folder to ``pythonxy\mingw\bin``
     and ``pythonxy\mingw\lib``.

  j) 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"

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

Windows: Using the GPU
----------------------

Please note that these are tentative instructions (we have not yet been able to
get the GPU to work under Windows with Theano).
Please report your own successes / failures on the
`theano-users <http://groups.google.com/group/theano-users>`_ mailing list.

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 (at least version 3.1) does not.
If your ``USERPROFILE`` directory (the one you get into when you run ``cmd``)
contains such characters, you must edit your Theano configuration file to
use a compilation directory located somewhere else:

    .. code-block:: cfg

      [global]
      base_compiledir=path_to_a_directory_without_such_characters

  You also need to add in the configuration file those lines:

    .. code-block:: cfg

      [cuda]
      nvccflags=-LC:\Python26\libs

  Then
  
  1) Install CUDA driver (32-bit on 32-bit Windows, idem for 64-bit).
  
  2) Install CUDA toolkit 32-bit (even if you computer is 64-bit, 
     must match the Python installation version)
  
  3) Install CUDA SDK 32-bit
  
  4) Test some pre-compiled example of the sdk

  5) Download Visual Studio 2008 Express(free, VS2010 not supported by nvcc 3.1,
     VS2005, not available for download, but supported by nvcc, the non free version should work too)

  6) Follow the instruction in the GettingStartedWindows.pdf file from CUDA web 
     site to compile CUDA code with VS2008. If that don't work, you won't be 
     able to compile GPU code with Theano.

  7) Put into you PATH environment variable the directory where cl.exe is. 
     In my case it is: ``C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin``

  8) Make sure the Theano folder is in your ``PYTHONPATH`` environment variable.

  9) Then in Python do: ``import theano.sandbox.cuda``

     That will print some error if their is an error to compile the first CUDA file.

  10) Then run the Theano CUDA test file. In Windows command line (cmd.exe), 
      run the program nosetests inside the Theano repository. 
      nosetests is installed by Python(x,y).

Windows V2: Installing Python Components Individually
-----------------------------------------------------

DISCLAIMER: These are old installation instructions (to be revised).

Running Theano under Windows is currently achieved by using the `MinGW
<http://www.mingw.org>`__ port of the GCC compiler.
It could probably also run with `Cygwin <http://www.cygwin.com/>`__,
but this has not been tested yet.

- From `the MinGW files <http://sourceforge.net/projects/mingw/files/>`__,
  download the latest version of the ``Automated MinGW Installer`` and install
  it (keeping default options).

- From `the MinGW files <http://sourceforge.net/projects/mingw/files/>`__,
  download the latest ``MSYS Base System`` executable file and run it
  (note that the latest version of MSYS Base System may not contain an
  executable file, in which case it is easier to just use an
  older version, e.g. MSYS-1.0.11.exe).
  This will install MSYS (you can keep the default install options).
  It will also run a post-install script where it will ask you about the
  location of MinGW (typically ``c:/MinGW``).

- From `the MinGW files <http://sourceforge.net/projects/mingw/files/>`__,
  download the current version of ``GCC Version 4`` (full package with
  binaries, e.g.
  gcc-full-4.4.0-mingw32-bin-2.tar.lzma). Unpack it (you may use
  `7-Zip <http://www.7-zip.org>`__ to unpack files with the
  .lzma extension), copying the content into the root directory
  of your MinGW installation (if you obtain a .tar file, make
  sure you expand it as well, either with `7-Zip <http://www.7-zip.org>`__
  or through the ``tar`` command on the MSYS command line).

- If you are familiar with vi, you may find useful to download and install
  ``MSYS vim`` (this is done in a similar way to GCC 4).
  This is strictly optional and mostly helpful to edit configuration files
  from within MSYS.

- Run MSYS (Start/Programs/MinGW/MSYS/MSYS) and check the installation
  by verifying that the proper version of GCC is found:

    .. code-block:: bash

        gcc --version

  You may also decide to change the location of your home directory by
  adding a line at the beginning of msys.bat, that would look like
  ``set HOME=C:\My\Home\For\MinGW`` (you can also set a global ``HOME``
  environment variable within Windows, but this could affect more programs).

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

- 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 the line
  ``export PATH=$PATH:/c/Python26:/c/Python26/Scripts``
  (for Python 2.6).

- Install a ``BLAS`` library. Note that although the following instructions
  will give you a generic way to build your own library, there may exist
  better (more optimized) versions of BLAS available for your system, but
  these have not been tested for Windows at this time.
  To build BLAS, download the latest version of `LAPACK <http://www.netlib.org/lapack/>`__
  (typically lapack.tgz), then issue the following commands in MSYS
  (for LAPACK 3.2.1):
  
    .. code-block:: bash

        tar zxvf lapack.tgz
        cd lapack-3.2.1
        gfortran -shared -O3 -o libblas.dll BLAS/SRC/*.f
        cp libblas.dll /mingw/lib
        mv libblas.dll /mingw/bin

- Edit (or create) your ``$HOME/.theanorc`` and add the following section:

    .. code-block:: cfg

        [blas]
        ldflags = -lblas

- Install `Mercurial <http://mercurial.selenic.com/downloads/>`__
  (you can use the regular Windows release, you do not need TortoiseHg).

- In order to run Theano's test-suite, you will need `nose
  <http://somethingaboutorange.com/mrl/projects/nose>`__.
  After unpacking its source code, you can build and install it from within
  the code directory by:

    .. code-block:: bash

        python setup.py install

- Install Theano using the above :ref:`install_bleeding_edge` installation instructions
  (using ``easy_install`` will require additional packages and has not been
  tested yet, while the latest official Theano release is also untested at this
  time).
  In particular, do not forget to make the Theano package accessible from
  Python, e.g. by adding to your ``.profile`` a line like
  ``export PYTHONPATH=PYTHONPATH:$HOME/Theano``.

- Please note that at this time, some tests (launched using ``nosetests``) are
  still failing under Windows: we are working on fixing them.
  It may also happen that many tests may fail while running the test-suite,
  due to insufficient memory resources (in which case you will probably get an
  error of the type ``"Not enough storage is available to
  process this command"``): one workaround is to run nosetests
  multiple times under individual subdirectories.
  

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
