.. _install:


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


Requirements
------------

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

    Linux, Mac OS X or Windows operating system
        We develop mainly on 64-bit Linux machines. other architectures are
        not well-tested.

    Python_ 2 >= 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++``, ``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.7.1
        Earlier versions could work, but we don't test it.

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

.. _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://nose.readthedocs.org/en/latest/>`_ >= 1.3.0 and `nose-parameterized <https://pypi.python.org/pypi/nose-parameterized/>`_ >= 0.5.0
        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.

    `graphiz <http://www.graphviz.org/>`__ and either `pydot-ng <https://github.com/pydot/pydot-ng>`__ or `pydot <https://code.google.com/p/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: :ref:`gpuarray`.)

        :note: OpenCL support is still minimal for now.

.. _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
.. _libgpuarray: http://deeplearning.net/software/libgpuarray/installation.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:

Docker images
~~~~~~~~~~~~~

Builds of Theano are available as `Docker <https://www.docker.com/whatisdocker>`_ images:
`Theano Docker (CPU) <https://hub.docker.com/r/kaixhin/theano/>`_ or `Theano Docker (CUDA) <https://hub.docker.com/r/kaixhin/cuda-theano/>`_.
These are updated on a weekly basis with bleeding-edge builds of Theano. Examples of running bash in a Docker container
are as follows:

.. code-block:: bash

    sudo docker run -it kaixhin/theano
    sudo docker run -it --device /dev/nvidiactl --device /dev/nvidia-uvm --device /dev/nvidia0 kaixhin/cuda-theano:7.0

For a guide to Docker, see the `official docs <https://docs.docker.com/userguide/>`_. For more details on how to use the
Theano Docker images, including requirements for CUDA support, consult the `source project <https://github.com/Kaixhin/dockerfiles>`_.

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

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

.. code-block:: bash

    nosetests theano

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

.. code-block:: bash

    pip install Theano --user

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

.. note::

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

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

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

.. only:: html

   Master Tests Status:

   .. raw:: html

      <a href="http://travis-ci.org/Theano/Theano/builds"><img src="https://secure.travis-ci.org/Theano/Theano.png?branch=master" /></a>&nbsp;

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

The following are general instructions that will set you up with the
bleeding-edge version of Theano and allow you to hack it. First,
get the code using `Git <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.


Specific git commit
~~~~~~~~~~~~~~~~~~~

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

.. code-block:: bash

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



.. _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=cuda1``.

    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, especially on more recent computers, against the
precompiled one). On Fedora, ``sudo yum install atlas-devel``. Under Ubuntu,
``sudo apt-get install libatlas-base-dev libatlas-base`` or
``libatlas3gf-sse2`` if your CPU supports SSE2 instructions. Then set the
Theano flags ``blas.ldflags`` to ``-lf77blas -latlas -lgfortran``. Note that
these flags are sometimes OS-dependent.

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

.. note::

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

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

.. note::

    If you have problems linking with MKL, `Intel Line Advisor
    <http://software.intel.com/en-us/articles/intel-mkl-link-line-advisor>`_
    and the `MKL User Guide
    <http://software.intel.com/sites/products/documentation/doclib/mkl_sa/11/mkl_userguide_lnx/index.htm>`_
    can help you find the correct flags to use.

.. _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 <https://developer.nvidia.com/cuda-toolkit>`_.  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``.

.. note::

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

    :ref:`Ubuntu instructions <install_ubuntu_gpu>`.

Next, install `libgpuarray <http://deeplearning.net/software/libgpuarray/installation.html>`_.

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=cuda,floatX=float32'``.
You can also set these options in the .theanorc file's ``[global]`` section:

     .. code-block:: cfg

        [global]
        device = cuda
        floatX = float32

Note that:

    * If your computer has multiple GPUs and you use 'device=cuda', the driver
      selects the one to use (usually cuda0).
    * You can use the program ``nvidia-smi`` to change this policy.
    * You can choose one specific GPU by specifying 'device=cudaX', 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.

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

Mac OS
------

There are various ways to install Theano dependencies on a Mac. Here
we describe the process in detail with Canopy, Anaconda, Homebrew or
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 Canopy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are working in academia, the easiest way to install most of the
dependencies is to install
`Canopy <http://enthought.com/products/canopy/>`_.
If you are affiliated with a university (as student or employee), you
can download the installer for free.

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

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

.. code-block:: bash

    $ pip install Theano

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

.. code-block:: bash

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

See the section `install_bleeding_edge`_ for more
information on the bleeding edge version.

Then you must install the compiler. See :ref:`compiler_osx` below.

.. note::

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


Anaconda
~~~~~~~~

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

The Anaconda installation includes in particular Python (and the
development headers), NumPy, SciPy, nose, sphinx, pip, and a
acceptable BLAS version.

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

.. code-block:: bash

    $ pip install Theano

To install the missing Theano optional dependency (pydot):

.. code-block:: bash

    $ conda install pydot-ng

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

.. code-block:: bash

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

See the section `install_bleeding_edge`_ for more
information on the bleeding edge version.

Then you must install the compiler. See :ref:`compiler_osx` below.

.. note::

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

.. _compiler_osx:

Installing the compiler
~~~~~~~~~~~~~~~~~~~~~~~

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

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


Homebrew
~~~~~~~~

Install python with homebrew:

.. code-block:: bash

    $ brew install python # or python3 if you prefer

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

.. code-block:: bash

    $ pip install numpy scipy

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

.. code-block:: bash

    $ brew tap homebrew/python
    $ brew install numpy --with-openblas
    $ brew install scipy --with-openblas


Then install theano as usual:

.. code-block:: bash

    $ pip install Theano --user

Or for the bleeding-edge version:

.. code-block:: bash

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


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

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

Next, install `libgpuarray <http://deeplearning.net/software/libgpuarray/installation.html>`_.

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

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

:ref:`install_windows` provides step-by-step instructions on how to install Theano on 32- or 64-bit Windows systems, using freely available
tools and compilers.

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


Windows Installation References
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. http://stackoverflow.com/questions/9047072/windows-python-version-and-vc-redistributable-version
2. http://stackoverflow.com/questions/1865069/how-to-compile-a-64-bit-application-using-visual-c-2010-express
3. http://blog.victorjabur.com/2011/06/05/compiling-python-2-7-modules-on-windows-32-and-64-using-msvc-2008-express/
4. http://stackoverflow.com/questions/126279/c99-stdint-h-header-and-ms-visual-studio
5. http://stackoverflow.com/questions/11182765/how-can-i-build-my-c-extensions-with-mingw-w64-in-python
6. https://mail.python.org/pipermail/python-announce-list/2014-September/010457.html


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