If you have any issues with installation, feel free to raise an issue on GitHub outlining your approach and any errors you received.

Simple installation with pip

The matador package can be found on PyPI under the name matador-db and installed with pip install matador-db, preferably in a fresh virtual environment (see conda instructions below). Extra dependencies may be installed with e.g. pip install matador-db[all].

Development installation with conda/pip

The tl;dr way to install matador, on e.g. a computing cluster, is as follows:

  1. Clone the matador source onto your local machine git clone

Optional (but recommended) steps:

  1. Install conda, if you have not already. There may be a package available already if you are using a supercomputer (e.g. anaconda-compute/2.2.0-python3 on ARCHER 30/10/2017).

  2. Create a new conda environment to install matador into (conda create -n matador python=3.7) and activate it with (conda activate matador).

  3. Install some of the heavier requirements (e.g. NumPy and SciPy) through conda with conda install --yes --file requirements/requirements.txt.

Required steps:

  1. Run pip install . from inside the top-level matador directory, or pip install -e . for an editable developer install.

  2. You now have a basic matador API installation, if you wish to use all matador features, install extra dependencies from the other requirements files inside requirements/ using either conda or pip. If you wish to just install everything use pip install .[all].

  3. To use matador, you will need to activate the conda environment from step 2, by running conda activate matador. You will also need this in e.g. any job scripts. After installing the test dependencies with pip install .[test], you can test your installation using python -m unittest discover -v -b or simply py.test. By default this will look for an MPI-enabled executable called castep on your $PATH to run CASTEP tests.


Below are some problems encountered on various machines that may be helpful:

  1. (10/09/2019) When installing with conda, if you receive the following error (or similar): /home/#####/.local/conda/envs/matador/compiler_compat/ld: build/temp.linux-x86_64-3.6/psutil/_psutil_common.o: unable to initialize decompress status for section .debug_info, then you are using a modern compiler that breaks conda’s attempts to be backwards compatible (in this case it was GCC 9). The simple fix is to rename/remove the copy of ld inside your conda environment (path in the message above) such that your system ld is used.

  2. (10/10/2017) On some machines (e.g. ARCHER/Thomas) you may receive permissions errors at step 5; if so, try moving matador’s .git and install again (mv .git $HOME/matador_git_stash; pip install . ; mv $HOME/matador_git_stash .git).

  3. Some dependencies may not have compiled packages (wheels) for your distribution on PyPI, and may have compilation errors. In this case, you could try finding the relevant package on conda instead.