GNU/Linux#

Install via Conda#

Warning

At this time, we do not provide a conda package for our GUI tools. This means if you want to install e.g., TOPPView or SwathWizard for use in for example one of our tutorials, please refer to a different installation method below.

You can use conda or mamba to install the OpenMS library and tools without user interface. Depending on the conda channel, you can obtain release versions (bioconda channel) and nightly versions (openms channel).

  1. Follow the instructions to install conda or mamba. In the following, every mention of conda may be substituted by mamba for faster environment solving.

  2. We recommend to create a new environment with one of the supported python version versions:

     conda create -n openms python=3.10
    
  3. Add some channels to find dependencies:

     conda config --add channels defaults
     conda config --add channels bioconda
     conda config --add channels conda-forge
    

    Note

    You can also add the channels for your current environment only with the --env option.

    Warning

    The order of the channels is important!

    Note

    conda-forge might already be added if you are using Mambaforge.

  4. Install any of the following packages related to OpenMS

    openms contains all OpenMS C++ command-line tools. GUI applications like TOPPView currently cannot be installed via conda.

    libopenms is the C++ library required for the OpenMS C++ Tools to work. This is also an auto-installed dependency of openms.

    pyopenms is the python package that allows to use algorithms from libopenms in Python.

    openms-thirdparty are external tools that are wrapped in OpenMS with adapters. This package is required to use the adapters in the openms package.

    Warning

    Due to unavailability of a large part of the thirdparty tools for macOS via conda, we are not providing a openms-thirdparty package on macOS either.

    via bioconda for release versions

    conda install openms
    
    conda install libopenms
    
    conda install pyopenms
    
    conda install openms-thirdparty
    

    or our own openms channel for nightly snapshots (which are build based on the same bioconda dependencies)

    conda install -c openms openms
    
    conda install -c openms libopenms
    
    conda install -c openms pyopenms
    
    conda install -c openms  openms-thirdparty
    

Install via package managers#

Packaged versions of OpenMS are provided for Fedora, OpenSUSE, Debian, and Ubuntu. You can find them to download here. For other GNU/Linux distributions or to obtain the most recent version of the library, installation should be done via building from the source code.

Important

These packages are not directly maintained by the OpenMS team and they can not be guaranteed to have the same behaviour as when building it from source code. Also, their availability and version is subject to change and support might be limited (due to unforeseen or untested behaviour). It is suggested not to install them parallel to our Debian package.

Note

Some thirdparty software used via adapter tools in OpenMS might also require an installed JavaVM.

Install via the provided Debian package#

For Debian-based Linux users, it is suggested to use the deb-package provided. It is most easily installed with gdebi which automatically resolves the dependencies available in the PPA Repositories.

sudo apt-get install gdebi
sudo gdebi /PATH/TO/OpenMS.deb

If you encounter errors with unavailable packages, troubleshoot using the following steps.

  1. Qt5 (or one of its packages, e.g. qt5xbase) is missing.

    It might be because your Debian is too old to have a recent enough version in its official repositories. It is suggested to use the same packages that are used while building (make sure to adapt the Qt version and your Debian/Ubuntu version, here Xenial):

    sudo add-apt-repository ppa:beineri/opt-qt59-xenial
    sudo apt-get update
    

    Run the installation again.

  2. ICU with its libicu is missing.

    You can find the missing version on pkgs.org and install it with gdebi, too. You can have multiple versions of ICU installed.

  3. Error while executing a tool

    To ensure the tool functionality, make sure you add the OPENMS_DATA_PATH variable to your environment as follow export OPENMS_DATA_PATH=/usr/share/OpenMS

  4. Thirdparty installation of Qt5 in step 1

    Make sure you source the provided environment file using: source /opt/qt59/bin/qt59-env.sh

  5. Adapters are not finding thirdparty applications

    Executables for thirdparty applications can be found in: /usr/share/OpenMS/THIRDPARTY Add the folders in your PATH for a convenient use of the adapters.

Run OpenMS inside a (Bio)Container#

  1. Install a containerization software (e.g., Docker or Singularity)

  2. Pull an image from one of the following registries:

  • OpenMS GitHub Container Registry for nightly binaries AND releases:

    On our registry, we provide one image for the library (with contrib) and one for the executables (with thirdparty).

    1. openms-library

    2. openms-executables

    They can be pulled/run via the following commands:

    docker pull ghcr.io/openms/openms-library
    docker pull ghcr.io/openms/openms-executables
    
    singularity run ghcr.io/openms/openms-library-sif
    singularity run ghcr.io/openms/openms-executables-sif
    

    Note

    Per default this results in the download of the latest nightly snapshot. Specify a release version (e.g., docker pull ghcr.io/openms/openms-library:3.1.0 to receive a stable version.

  • Otherwise, the BioContainers Registries and the associated Galaxy project provide native containers based on our bioconda packages for both Docker and Singularity.

    1. BioContainers libopenms

    2. BioContainers openms

    3. BioContainers openms-thirdparty

    4. BioContainers pyOpenMS

    Images of the containers can be pulled via or one of the following commands:

    docker pull quay.io/biocontainers/libopenms
    docker pull quay.io/biocontainers/openms
    docker pull quay.io/biocontainers/pyopenms
    docker pull quay.io/biocontainers/openms-thirdparty
    
    singularity run https://depot.galaxyproject.org/singularity/libopenms
    singularity run https://depot.galaxyproject.org/singularity/openms
    singularity run https://depot.galaxyproject.org/singularity/pyopenms
    singularity run https://depot.galaxyproject.org/singularity/openms-thirdparty
    

Note

If Singularity images fail to download or run, try to use the Docker images as Singularity will automatically convert them.

Dockerfiles to build different kind of images (e.g., for ArchLinux) yourself can be found on GitHub in our OpenMS/dockerfiles repository. They usually follow our build instructions closely, so you can have a look on how this is done in a clean environment.

Build OpenMS from source#

To build OpenMS from source, follow the build instructions for Linux.