Quick start

This document provides simple recipes for some specific installation scenarios. Refer to Full installation instructions for complete documentation about prerequisites and building from source code.


This documentation is for gmxapi 0.0.7 on GROMACS 2019. For gmxapi 0.1 or later and GROMACS 2020 or later, refer to http://manual.gromacs.org/current/gmxapi/userguide/install.html

Please report bugs or updates at https://github.com/kassonlab/gmxapi/issues

Simple “pip” installation

In the simplest case, the following should just work:

git clone https://github.com/kassonlab/gmxapi.git
cd gmxapi
git checkout release-0_0_7
pip install -r requirements.txt
pip install .


The trailing . after pip install indicates to install from the current directory.

pip will need to be able to find a GROMACS 2019 installation with gmxapi enabled. When building GROMACS, make sure to use the -DGMXAPI=ON CMake option. Then, make sure you tell pip where to find the GROMACS installation by setting gmxapi_DIR or just “source”ing the GMXRC file, as usual.

If you install to the directory /path/to/gromacs, then you should have a /path/to/gromacs/bin/GMXRC configuration script that you would normally run or source before using gmx command line tools. Do that first. E.g. for the bash shell:

source /path/to/gromacs/bin/GMXRC


We recommend installing in a Python virtual environment. If not using a venv you can tell pip to install the package to your home directory by including the --user flag to pip install.


Check out our pre-built Docker images for a quick look at gmxapi or as a starting point for simulations in containers.

The Dockerfile recipes may also be useful references when building the software.

Docker images are based on the Jupyter Docker Stacks.

For a Jupyter notebook, launch docker run --rm -ti -p 8888:8888 gmxapi/sample_restraint and point your browser at the URL that is displayed. Then navigate to sample_restraint -> examples

For a bash shell, just run docker run --rm -ti gmxapi/sample_restraint bash


Thanks to jmhays for contributing Singularity recipes.

singularity pull --name customname.img shub://jmhays/singularity-restrained-ensemble

See https://www.singularity-hub.org/collections/1825/usage for variants.

“User” installation

In the simplest case, if dependencies are already installed and you have an appropriate Python installation on your default PATH, something like the following should just work. This will install the gmx Python package into the default “user site-packages” directory for the Python installation you are using so that you can just run Python normally and import gmx.

wget https://github.com/gromacs/gromacs/archive/release-2019.zip
unzip release-2019.zip

mkdir gromacs-build
pushd gromacs-build
cmake ../gromacs-release-2019 -DGMXAPI=ON -DCMAKE_INSTALL_PREFIX=$HOME/gromacs
make install

source $HOME/gromacs/bin/GMXRC

wget https://github.com/kassonlab/gmxapi/archive/release-0_0_7.zip
unzip release_0_0_7.zip

mkdir gmxapi-build
pushd gmxapi-build
cmake ../gmxapi-release-0_0_7 -DGMXAPI_USER_INSTALL=ON
make install


If your computer has more resources available, you can try to speed up the build by telling make to run in parallel. To use 8 threads, for instance, do make -j8 install.

Conda installation

gmxapi does not provide a Conda binary package, but the following documentation may work to prepare a Conda environment for gmxapi.

Get and install Anaconda. Alternatively, on an HPC system an Anaconda installation may already be provided with a module system. For example:

module load gcc
module load cmake
module load anaconda3
module load openmpi

You don’t have to follow all of the instructions for setting up your login profile if you don’t want to, but if you don’t, then the conda and activate commands below will have to be prefixed by your conda installation location. E.g. ~/miniconda3/bin/conda info or source ~/miniconda3/bin/activate myEnv

Create a conda virtual environment. Replace myEnv below with whatever convenient name you choose.

conda create -n myGmxapiEnv python=3 pip setuptools cmake networkx mpi4py

Activate, or enter the environment.

source activate myGmxapiEnv

Install the GROMACS gmxapi fork.

git clone https://github.com/kassonlab/gromacs-gmxapi.git gromacs
mkdir build
cd build
make -j12 && make install
source $HOME/gromacs-gmxapi/bin/GMXRC

Make sure dependencies are up to date.

MPICC=`which mpicc` pip install --upgrade mpi4py

Install the Python module.

git clone https://github.com/kassonlab/gmxapi.git gmxapi
cd gmxapi
mkdir build
cd build
cmake ..
make install

Minimal Ubuntu system set up example

This section attempts to document installation in a constrained and minimal environment, such as might be encountered in a container or testing system.

Before proceeding, consider whether an existing Docker or Singularity recipe may be sufficient for you.

The following is tested for Ubuntu 14 using the ubuntu/trusty image from Docker Hub <hub.docker.com>

As root:

apt-get update
apt-get install software-properties-common
apt-add-repository -y "ppa:ubuntu-toolchain-r/test"
apt-get update

apt-get -yq --no-install-suggests --no-install-recommends install \
    cmake \
    cmake-data \
    libblas-dev \
    libcr-dev \
    libfftw3-dev \
    liblapack-dev \
    libmpich-dev \
    libxml2-dev \
    make \
    mpich \

# You probably want one or two more packages for convenience. For example:
apt-get -yq --no-install-suggests --no-install-recommends install \
    git vim wget git

To manage Python installations, you could either use the native package manager, or something like pyenv (see below). In Ubuntu 14, the following packages should be sufficient.

apt-get install python python-dev python3 python3-dev

For additional ideas, take a look at our Docker recipes or our .travis.yml Travis-CI configuration.