Installation via package manager

We recommend you install mdciao via the pip Python package installer:

pip install mdciao

Installation via the conda Python package manager is not ready yet.


As almost any Python module, mdciao comes with some dependencies that will be installed along when installing mdciao. If you don’t want mdciao to alter the existing python installation, we highly recommend to create a separate, virtual python environment to install mdciao into. More info on how to do this in the note about the Python interpreter and environment.


If you are interested in latest mdciao features, please use the Installation from source.

Installation from source


If you are not familiar with Python environments, please read this Python interpreter and environment note before continuing.

  • Clone or download mdciao’s github repository to your preferred programs or software folder. If you are using a terminal and have git installed, simply:

    git clone

    Cloning with git will allow you to easily get fixes and new features if you pull regularly. If you don’t have git, you can use wget (or MacOs equivalent) to simply download a snapshot of the repository at its current status (you’ll have to re-dowload again every time to get fixes and new features):


    and if you don’t have wget simply browse to mdciao’s github repository and download from there via your browser.

  • If you are not familiar with Python environments, please read this Python interpreter and environment note before continuing.

  • cd to the (unzipped) mdciao directory and execute the file:

    python install

This should install mdciao along with all its dependencies. Optionally using develop instead of install means that the mdciao in your Python path points directly to the sources directory, s.t. changes in the source take effect immediately without re-installing


On some occasions the above commands don’t install numpy, cython or mdtraj properly. Should that happen to you, we recommend issuing:

pip install cython
pip install numpy
pip install mdtraj


conda install cython
conda install numpy
conda install mdtraj -c conda forge

before installing mdciao.

Operating systems and Python versions

mdciao is developed in GNU/Linux, and CI-tested via github actions for GNU/Linux (MacOs is failing, see this). Compatible Python versions are currently 3.6, 3.7, 3.8, and 3.9. So everything should work out of the box in these conditions. Please see this warning for problems during installation from source.

Python interpreter and environment

conda and pip are very popular, user friendly package managers. A very nice feature of conda is that it installs its own python interpreter, separate from the system’s Python. It does so in the user’s home directory, s.t. no root privileges are needed at any moment.

This means that it’s very hard to “break” local Python installations (your own or shared installations, like in clusters). So, don’t be afraid to use conda and mess up your Python environment as many times as you like. Wiping and re-installing individual environments is easy (conda remove -n my_test_env –all), same with entire conda installations (delete ~/anaconda3 or ~/miniconda3 from your home directory). None of this will alter your OS-wide Python installation at all!

If you already have conda, and don’t want to clutter the base environment, we recommend you create a new environment:

conda create -n for_mdciao
conda activate for_mdciao

If you prefer pip, please see their documentation on creating a virtual environment.

If neither pip nor conda is installed in your system, we recommend you install the bare-bones conda distribution, miniconda and build from there:

  • Download the latest miniconda from here

  • Install by issuing:


and follow the prompt instructions. If you don’t want the anaconda Python interpreter to be your default, just answer no to the last question.