Quick and Simple

From a terminal install the latest stable version with pip:

pip install pychemia --user

It will install pychemia and all its dependencies in your $HOME folder. If you want a central installation you can install directly with:

sudo pip install pychemia

Installing PyChemia with pip

This is probably the easiest way, pip will download the code, check and eventually install dependencies and installing the package on a system-wide place or the home directory. All you have to do is execute this command:

sudo pip install pychemia

or for python 3.x:

sudo pip3 install pychemia

If you are on a machine where you do not have superuser privileges you can install pychemia on your home directory by adding the command ‘–user’:

pip install pychemia --user

or for python 3.x:

pip3 install pychemia --user

Uninstall or upgrade pychemia is also very simple with pip:

pip uninstall pychemia

pip install pychemia --upgrade

Installing PyChemia with virtualenv

PyChemia requieres a relative recent version of Python (Python 2.7 appeared on July 3, 2010). However, it is common for some HPC infraestructures to use Linux installations such as RHEL 6 that only provides python 2.6 dating back to 2008. You can contour this situation by using Software Collections:

Install a more recent version of python and virtualenv. After that you can install PyChemia and its dependencies contained on a virtual environment following this commands:

  1. Create a new virtual environment, lets call it “venv_pcm”

virtualenv venv_pcm

  1. Activate the environment by sourcing the activate script

source venv_pcm/bin/activate

3. You will notive that the prompt changes and you get your path pointing to a containerized python environment where you can install PyChemia and its dependencies

pip install pychemia

4. Shortly after that, you will get all the dependencies installed and the software ready for use without touching the libraries and modules installed by your Linux distribution. You can leave the virtual environment with the command:


To re-enable the environment all you have to do is execute step 2 and you get the environment ready to work.

Installing PyChemia from github

The current stable repository for PyChemia is on Github, you can download the master branch with the command:

git clone

If you get a message such as:

$ git clone
-bash: git: command not found

You need to install git first. On machines from the Debian ‘lineage’ (Ubuntu, Mint, and many others) you can use the command:

sudo apt-get install git

On systems with yum you can use:

sudo yum install git

Now that you have ‘cloned’ the PyChemia repository you have two options. Install the package by using the set of commands:

cd PyChemia
python setup build
python setup install --user

Use python3 for the commands above, if you want to use python 3.x instead.

Another alternative is add path where you downloaded the repository to the variable $PYTHONPATH. You can do that by editing your .bashrc file. Supposing that you execute the git clone command directly on your home directory you can add the path for PyChemia adding this line to your .bashrc:


If you want the changes on .bashrc take inmediate effect execute:

source $HOME/.bashrc


PyChemia relies on the presence of at least this libraries:

numpy  >= 1.12.0
scipy  >= 0.18.0
future >= 0.16.0
spglib >= 1.9.9
pymongo >= 3.4.0

Most Linux distributions will probably include older versions of those dependencies. HPC Linux clusters usually have a very conservative approach related to packages and even older versions of those dependencies will be installed the system or completely absent from it.

The packages numpy and scipy are well known python packages for Linear Algebra and general scientific computing. PyChemia is able to run on Python 2 and 3 using the same sources. The python package future is a small package that helps keeping compatibility with python 2 and python 3 on the same source code. The package spglib is a C-library with python wrappers for computing space groups and related functionality. The package pymongo offers connectivity with a MongoDB database. MongoDB is a document-based NoSQL database engine. PyChemia uses MongoDB databases for storing collections of structures or properties and parameters associated to them.

We try to keep the dependencies of PyChemia to a very minimum. Some other libraries provides extra functionality that could be necessary for some tasks. Consider install nose and matplotlib. You can do that using pip with the command:

sudo pip install nose matplotlib

Remember that you can use --user if you want to install on your home directory without special privileges. Matplotlib is the ‘standard de-facto’ for 2D plots on python. Many of the functionalities on ‘pychemia.visual’ subpackage depends on it. Nose is a python package for executing automatize tests for PyChemia. If you want to use it more information is below.

Importing the library

No matter how you installed PyChemia, you should be able to load the library. You can use the traditional python terminal, for example:

$ python3.5
Python 3.5.1 (default, Mar  2 2016, 03:38:02)
[GCC 4.2.1 Compatible Apple LLVM 7.0.2 (clang-700.1.81)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import pychemia

Version: 0.1.2
Path:    /Users/guilleaf/PyChemia/pychemia
Date:    May 13, 2016

Python version=3.5.1 (default, Mar  2 2016, 03:38:02)
[GCC 4.2.1 Compatible Apple LLVM 7.0.2 (clang-700.1.81)]

pymongo Not Found
     numpy     1.11.0   /opt/local/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages/numpy
     scipy     0.17.1   /opt/local/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages/scipy
    mayavi            Not Found
Scientific            Not Found
matplotlib      1.5.1   /opt/local/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages/matplotlib
    future     0.15.2   /opt/local/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages/future
      nose      1.3.7   /opt/local/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages/nose
  coverage      4.0.3   /opt/local/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages/coverage
    spglib      1.9.4   /Users/guilleaf/Library/Python/3.5/lib/python/site-packages/spglib
    pyhull            Not Found
  pymatgen            Not Found
      qmpy            Not Found
       ase            Not Found

The method will inform about the several libraries that PyChemia uses, both mandatory and optional, their versions and path. That could be informative in case of something not working as expected.

Testing with nose

It is always important to test a library, not only from the developer point of view, but also for an user. Nose is a python package that offers a simple command to execute predefined test for a python package and report any errors or inconsistencies from the expected resuts.

Direct the terminal to the place where PyChemia is located. Lets suppose that you have pychemia on /Users/guilleaf/PyChemia, test PyChemia using the command:

cd /Users/guilleaf/PyChemia
nosetests -v

The name of the command could have small variations according to your distribution. On a MacOS using macports the name could be for example nosetests-2.7 or nosetests-3.5 for python 2 and 3 respectively.

nosetests will search for tests on the entire package and subpackages. If everything is fine (and you use -v for verbose output) you will get something like:

Example of a simple calc                                     : ... ok
Example of a multiple calc                                   : ... ok

Ran 38 tests in 5.469s


That is an indication that all tests were successful and eventually you are ready to use the library.