path: root/doc/source/install.rst

Installation steps
==================

*silx* supports `Python <https://www.python.org/>`_ versions 2.7, 3.4 or later.

To install *silx* on Windows, read the `Windows instructions`_.

To install *silx* on Linux, read the `Linux instructions`_.

To install *silx* on MacOS, read the `MacOS instructions`_.

You will find the simple instructions for each platform at the beginning of each section, followed by more detailed instructions concerning dependencies and alternative installation methods.

For all platform, to install *silx* from the source, see `Installing from source`_.

To install *silx* in a virtualenv, read :ref:`silx-venv`.

Dependencies
------------

The only mandatory dependency of *silx* is `numpy <http://www.numpy.org/>`_.

Yet, a set of `Optional dependencies`_ is necessary to enable all *silx* features.

Optional dependencies
+++++++++++++++++++++

The GUI widgets depend on the following extra packages:

* A Qt binding: either `PyQt5, PyQt4 <https://riverbankcomputing.com/software/pyqt/intro>`_ or `PySide <https://pypi.python.org/pypi/PySide/>`_
* `matplotlib <http://matplotlib.org/>`_
* `PyOpenGL <http://pyopengl.sourceforge.net/>`_
* `IPython <https://ipython.org/>`_ and `qt_console <https://pypi.python.org/pypi/qtconsole>`_ for the ``silx.gui.console`` widget.

Tools for reading and writing files depend on the following packages:

* `h5py <http://docs.h5py.org/en/latest/build.html>`_ for HDF5 files
* `fabio <https://github.com/silx-kit/fabio>`_ for multiple image formats

*silx.opencl* and *silx.image.sift* further depends on OpenCL and the following packages to :

* `pyopencl <https://mathema.tician.de/software/pyopencl/>`_
* `Mako <http://www.makotemplates.org/>`_

Build dependencies
++++++++++++++++++

In addition to run-time dependencies, building *silx* requires a C/C++ compiler, `numpy <http://www.numpy.org/>`_ and `cython <http://cython.org>`_ (optional).

On Windows it is recommended to use Python 3.5, because with previous versions of Python, it might be difficult to compile the extensions.

This project uses cython to generate C files.
Cython is not mandatory to build *silx* and is only needed when developing binary modules.
If using cython, *silx* requires at least version 0.18 (with memory-view support).


Linux instructions
------------------

If NumPy is not installed on your system, you need to install it first
either with the package manager of your system (recommended way) or with pip::

    pip install numpy --user

On Linux, you can install *silx* in your home directory::

    pip install silx --user

.. note::
    
    Replace the ``pip`` command with ``pip3`` to install *silx* or any other library for Python 3.

.. note::
    
    This installs *silx* without the optional dependencies. 
    
To install *silx* on Debian 8, see `Installing a Debian package`_.
This method requires **sudo** privileges, but has the benefit of installing dependencies in a simple way.

CentOS 7 rpm packages are provided by Max IV at the following url: http://pubrepo.maxiv.lu.se/rpm/el7/x86_64/

Fedora 23 rpm packages are provided by Max IV at http://pubrepo.maxiv.lu.se/rpm/fc23/x86_64/

An Arch Linux (AUR) package is also available: https://aur.archlinux.org/packages/python-silx

You can also choose to compile and install *silx* from it's sources:
see `Installing from source`_.

.. note::

    The Debian packages `python-silx` and `python3-silx` will not install executables (`silx view`, `silx convert` ...).
    So in order to access those applications you should use: `python* -m silx appX`.
    For example to open the viewer:

    .. code-block:: python

        python -m silx view


Installing a Debian package
+++++++++++++++++++++++++++

Debian 8 (Jessie) packages are available on http://www.silx.org/pub/debian/ for amd64 computers.
To install it, you need to download this file::

    http://www.silx.org/pub/debian/silx.list

and copy it into the /etc/apt/source.list.d folder.
Then run ``apt-get update`` and ``apt-get install python-silx``

:: 

   wget http://www.silx.org/pub/debian/silx.list
   sudo cp silx.list /etc/apt/sources.list.d
   sudo apt-get update
   sudo apt-get install python-silx python3-silx

.. note::
    
    The packages are built automatically, hence not signed. 
    You have to accept the installation of non-signed packages.  

If the packages are not installed, it might be due to the priority list.
You can display the priority list using `apt-cache policy python-silx`.
If the Pin-number of silx.org is too low compared to other sources:
download http://www.silx.org/pub/debian/silx.pref into /etc/apt/preferences.d
and start the update/install procedure again.


Windows instructions
--------------------

The simple way of installing the *silx* library on Windows is to type following
commands in a command prompt::

    pip install silx
  
.. note::
    
    This installs *silx* without the optional dependencies.
    Instructions on how to install dependencies are given in the
    `Installing dependencies`_ section.
    
This assumes you have Python and pip installed and configured. If you don't,
read the following sections.


Installing Python
+++++++++++++++++

Download and install Python from `python.org <https://www.python.org/downloads/>`_. 

We recommend that you install the 64bits version of Python, which is not the default version suggested on the Python website. The 32bits version is limited to 2 GB of memory, and also we don't provide a silx wheel for it. This means that you would have to install silx from its sources, which requires you to install a C compiler first.

We also encourage you to use Python 3.5 or newer.

Configure Python as explained on `docs.python.org
<https://docs.python.org/3/using/windows.html#configuring-python>`_ to add
the python installation directory to your PATH environment variable.

Alternative Scientific Python stacks exists, such as `WinPython <http://winpython.github.io/>`_.
They all offer most of the scientific packages already installed which makes the installation of dependencies much easier.

Installing pip
++++++++++++++

Recent version of Python (`> 2.7.9` or `> 3.4`) provide pip by default.

If you have an older version of Python and you do not wish to upgrade it,
you can install pip yourself.

Download the script https://bootstrap.pypa.io/get-pip.py and execute it in a
command prompt::

    python get-pip.py  


Using pip
+++++++++

Configure your PATH environment variable to include the pip installation
directory, the same way as described for Python.

The pip installation directory will likely be ``C:\Python35\Scripts\``.

Then you will be able to use all pip commands listed in following in a command
prompt.


Installing dependencies
+++++++++++++++++++++++

Some of the dependencies may be simply installed with pip::

    pip install numpy
    pip install matplotlib
    pip install PyOpenGL
    pip install PyQt5
    pip install PySide

Regarding the `h5py` and `PyQt4` modules, you can find the wheels at
Christoph Gohlke's repository:

http://www.lfd.uci.edu/~gohlke/pythonlibs/

Download the appropriate `.whl` file for your system and install them with pip::

    pip install h5py*.whl
    pip install PyQt4*.whl
    
`PyQt5` can be downloaded as a binary package for `Python 3.5` on the
`Riverbank Computing website <https://www.riverbankcomputing.com/software/pyqt/download5>`_.
This package contains everything needed for `PyQt5`, including `Qt`.


Installing *silx*
+++++++++++++++++

Provided numpy is installed, you can install *silx* with::

    pip install silx


MacOS instructions
------------------

The easy way to install *silx* on MacOS, is::

    pip install silx

This should work without issues, as binary wheels of *silx* are provided on
PyPi.

Wheels are available for *h5py* on MacOS, so you can install it with::

    pip install h5py

If at the time of your installation a new version of *h5py* has been released but
the corresponding MacOS wheel is not ready, you should install the latest version including
a wheel: ``pip install h5py==2.6.0``

A PyQt5 wheel is now available for Python 3.5 on MacOS: https://pypi.python.org/simple/pyqt5/.
Download it and install it with::

    pip install PyQt5-5.6-cp35-cp35m-macosx_10_6_intel.whl

This should work for all versions of MacOS from 10.6.


Installing from source
----------------------

Building *silx* from the source requires some `Build dependencies`_.

Building from source
++++++++++++++++++++

Source package of *silx* releases can be downloaded from `the pypi project page <https://pypi.python.org/pypi/silx>`_.

After downloading the `silx-x.y.z.tar.gz` archive, extract its content::

    tar xzvf silx-x.y.z.tar.gz
    
Alternatively, you can get the latest source code from the master branch of the `git repository <https://github.com/silx-kit/silx>`_:  https://github.com/silx-kit/silx/archive/master.zip

You can now build and install *silx* from its sources::

    cd silx-x.y.z
    pip uninstall -y silx
    pip install . [--user]

Known issues
............

There are specific issues related to MacOSX. If you get this error::

  UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 1335: ordinal not in range(128)

This is related to the two environment variable LC_ALL and LANG not defined (or wrongly defined to UTF-8).
To set the environment variable, type on the command line::

  export LC_ALL=en_US.UTF-8
  export LANG=en_US.UTF-8

Advanced build options
++++++++++++++++++++++

In case you want more control over the build procedure, the build command is::

    python setup.py build

After this build, you will still need to install *silx* to be able to use it::

    python setup.py install [--user]

There are few advanced options to ``setup.py build``:

* ``--no-cython``: Prevent Cython (even if installed) to re-generate the C source code.
  Use the one provided by the development team.
* ``--no-openmp``: Recompiles the Cython code without OpenMP support (default for MacOSX).
* ``--openmp``: Recompiles the Cython code with OpenMP support (default for Windows and Linux).

To build the documentation (this requires `Sphinx <http://www.sphinx-doc.org/>`_), run::

    python setup.py build build_doc


Testing
+++++++

To run the tests of an installed version of *silx*, from the python interpreter, run:

>>> import silx.test
>>> silx.test.run_tests()