This note briefly describes how to install and use mermaid. It can be installed via *conda* or maybe simpler using python We also recommend using a conda virtual environment to keep the installation clean.

mermaid requirements

mermaid is based on the following:

  • python >= 3.6
  • pytorch >= 1.0

It runs on Linux and on OSX. Windows installs might be possible, but have not been tested (hence will likely not work out of the box) and are not officially supported.

Anaconda installation

If you have not done so yet, install anaconda. Simply follow the installation instructions here. This will provide you with the conda package manager which will be used to create a virtual environment (if desired, we highly recommend it) and to install all python packages that mermaid depends on.

Creating a conda virtual environment

It is best to install everything into a conda virtual environment. This can be done as follows.

conda create --name mermaid python=3.7 pip
conda activate mermaid

If you later want to remove this environment again, this can be done by executing

conda remove --name mermaid --all

Mermaid installation via conda

mermaid can conveniently be installed via conda. Once you have activated your desired conda environment (for example, the conda virtual environment created above) mermaid can be installed by executing

conda install -c pytorch -c conda-forge -c anaconda -c uncbiag mermaid

Once installed mermaid simply needs to be imported in your python program via

import mermaid

Mermaid development installation

Sometimes it is desirable to install mermaid for development purposes. To do this, first download the git repository

git clone

The repository’s main folder contains a file (see python setup file) for the setup file mermaid’s is based on and a general explanation of its use. For development purposes then simply execute

cd mermaid
python develop

This will install all library links and all missing packages and will allow mermaid imports.

Alternatively, mermaid can also be installed this way via executing

cd mermaid
python install

Creating the documentation

The documentation is created via sphinx. To build it first install graphviz (on OSX: brew install graphviz or via conda, see below). If you installed via the developer option (via you will also need to install pandoc (should be auto installed via conda). This can be done by following the instructions here (pypandoc will be auto installed via or by installing it manually via conda:

conda install -c conda-forge pandoc

Graphviz can also be installed via conda if desired:

conda install -c anaconda graphviz

Then execute the following to make the documentation

cd mermaid
cd docs
make html

This will create the docs in build/html. Current versions are hosted on readthedocs (

Running the code

The simplest way to start is to look example script demos/test_simple_interface,py, or to run the examples from the jupyter directory which contains various example jupyter notebooks. You can run the jupyter notebooks as follows (should be intalled if you installed via conda or python develop as described above):

cd mermaid
cd jupyter
jupyter notebook