Installation steps¶
PyMca supports most operating systems and different version of the Python programming language.
It can be installed as a stand alone application or as a Python module. The later offer a greater flexibility besides the possibility to make use of different features of PyMca in your own Python programs.
Stand-alone Executable¶
Stand-alone applications (aka. frozen binaries) are supplied for Windows and MacOS. They do not require any additional dependency and can be downloaded from here. Just download the installer for your platform.
Python module¶
The best use of PyMca can be achieved installing PyMca as a python package inside an existing Python installation. For Windows and MacOS there are pre-compiled modules available in order to simplify the task.
This table summarized the the support matrix of PyMca:
System |
Python vers. |
Qt and its bindings |
2.7, 3.5-3.6 |
PyQt4.8+, PyQt5.3+ |
|
2.7, 3.5-3.6 |
PyQt4.8+, PyQt5.3+ |
|
2.7, 3.4-3.6 |
PyQt4.8+, PyQt5.3+ |
For all platforms, you can install PyMca5 from the source, see Installing from source.
Installing Python¶
You can skip this section if you already have a properly configured Python installation.
Windows¶
Download and install Python.
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 binary wheel for it what means that you would have to install PyMca5 from its sources, which requires you to install a C compiler first.
We also encourage you to use Python 3.5 or newer, former versions are no more officially supported.
Configure Python as explained on docs.python.org to add the python installation directory to your PATH environment variable.
You may need to configure your PATH environment variable to include the pip installation directory.
MacOS¶
Python 2.7 is shipped by default but we recommend using Python 3.5 or newer to simplify the installation of the Qt library.
Download and install Python from python.org or, alternatively, install Python from the anaconda distribution
Open a terminal and type which python3 and which pip3. Those commands should give you back the location of the respective scripts if you have properly installed python.
Linux¶
For Linux please refer to the relevant documentation of your linux distribution.
Installing PyMca¶
This assumes you have Python and pip installed and configured. If you don’t, read the previous sections.
For MacOS and Windows this should work without issues, as binary wheels of PyMca are provided on PyPI.
Windows¶
The simple way of installing PyMca on Windows is to type the following commands in a command prompt:
pip install PyMca5
That install PyMca for command line use but all dependencies may be simply installed with pip.
A convenient set of dependencies can be installed with:
pip install -r https://raw.githubusercontent.com/vasole/pymca/master/requirements.txt
Note
Detailed instructions on how to install dependencies are given in the Installing dependencies section.
MacOS¶
It is exactly like with windows, perhaps you may need to replace pip by pip3 as follows:
pip uninstall pymca
pip uninstall PyMca5
pip install pymca
or
pip3 uninstall pymca
pip3 uninstall PyMca5
pip3 install PyMca5
A convenient set of dependencies can be installed with:
pip3 install -r https://raw.githubusercontent.com/vasole/pymca/master/requirements.txt
Note
Detailed instructions on how to install dependencies are given in the Installing dependencies section.
Linux¶
There are no frozen binaries or wheels available for linux. Nevertheless, there are strong chances that PyMca is available as a native package for your distribution.
If you need to build PyMca from its source code, and NumPy and fisx are not installed on your system, you need to install them first, preferably with the package manager of your system. If you cannot use the package manager of your system (which requires the root access), please refer to the Virtual Environment procedure explained in the silx documentation
Please refer to Installing from source
Note
The Debian packages python-pymca5 and python3-pymca5 will not install executables (pymca, pymcaroitool …). Please install the pymca package.
You can also install PyMca from its source code. While numpy and fisx are the only mandatory dependencies for command line usage, graphical widgets require Qt and matplotlib and management of HDF5 data files requires h5py.
Installing from source¶
To build PyMca from source requires the use of compiler. While this is not a problem under linux, it can be problematic for Windows or MacOS users. The installation of Visual Studio under windows or XCode under MacOS is beyond the purpose of this tutorial. Please refer to appropriate documentation sources.
Build dependencies¶
In addition to run-time dependencies, building PyMca requires a C/C++ compiler, numpy and cython (optional).
This project uses Cython (version > 0.21) to generate C files. Cython is now mandatory to build PyMca from the development branch and is only needed when compiling binary modules.
Building PyMca from the source requires NumPy and fisx installed that can be installed using:
pip install numpy
pip install fisx
Building from source¶
The most straightforward way is to use pip to take the sources from PyPI:
pip install PyMca5 --no-binary [--user]
Alternatively, the source package of PyMca releases can be downloaded from the pypi project page.
After downloading the PyMca5-x.y.z.tar.gz archive, extract its content:
tar xzvf PyMca5-x.y.z.tar.gz
cd PyMca5-x.y.z
pip uninstall -y PyMca5
pip install . [--user]
Alternatively, you can get the latest source code from the master branch of the git repository: https://github.com/vasole/pymca
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
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.
It is recommended to run the test suite of PyMca only after installation:
python -m PyMca5.tests.TestAll
Package the built into a wheel and install it:
python setup.py bdist_wheel
pip install dist/PyMca5*.whl
To build the documentation, using Sphinx:
python setup.py build build_doc
Dependencies¶
Tools for reading and writing HDF5 files depend on:
The GUI widgets depend on the following extra packages:
A Qt binding: either PyQt5, PyQt4, PySide, or PySide2
The following packages are optional dependencies:
silx for enhanced widgets
qt_console for the interactive console widget.
PyOpenGL for 3D and scatter plot visualization
It is expected that h5py and silx become required dependencies within short because:
h5py will become the preferred input/output file format of PyMca
silx provides a better widget library than the one currently supplied by PyMca
The complete list of dependencies with the minimal version is described in the requirements.txt at the top level of the source package.
Installing PyMca¶
Provided numpy is installed, you can install PyMca with:
pip install pymca
or
pip install PyMca5
For MacOS and Windows this should work without issues, as binary wheels of PyMca are provided on PyPI.
Please remember to replace pip by pip3 if that is what you are using.
All dependencies may be simply installed with pip. Please replace pip by pip3 if that is what you are using:
pip install -r https://raw.githubusercontent.com/vasole/pymca/master/requirements.txt
Conda installation¶
PyMca can be installed with conda from the conda-forge repository for all versions of Anaconda and Miniconda:
To install PyMca with all dependencies, including the GUI, use:
conda install -c conda-forge pymca silx
If you do not need the GUI, you can simply install it with:
conda install -c conda-forge pymca
Testing¶
To run the tests of an installed version of PyMca, from the python interpreter, run:
import PyMca5.tests
PyMca5.tests.testAll()
To run the test suite from the command line run:
python -m PyMca5.tests.TestAll
or
python3 -m PyMca5.tests.TestAll
