Installation on macOS

‘On macOS, how do I install Morpheus?’

Please note that the detailed information here in the installation FAQ refers to the latest Morpheus release. The installation of older Morpheus versions may differ. All essential instructions for installing Morpheus on macOS, including older versions, can always be found on the download page of the respective release.

Install Homebrew

Beginning with Morpheus version 2.2.6, Homebrew is required for installation on macOS. Homebrew is a free and open-source package manager for macOS (and Linux) that lets you easily install Morpheus, takes care of all dependencies needed for the simulator and the GUI and keeps everything up-to-date.

If Homebrew is not installed on your system yet, you can easily do so by pasting this line into Terminal.app and pressing Enter:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Furthermore, you have to add the so-called Morpheus tap once, through which the Morpheus.Lab team delivers the installation routines for macOS and all Morpheus updates.

brew tap morpheus-lab/morpheus

Install Morpheus

If Homebrew is present on your system, simply install the latest version of Morpheus with:

brew install morpheus

And follow possibly emerging instructions from Homebrew.

Depending on your system (Mac model, operating system, performance), the installation may take several minutes. For selected systems, pre-compiled binary packages are available, so-called ‘bottles’, which will then be downloaded automatically and speed up the installation significantly (in some cases to only a few seconds).

Add Morpheus.app to the App Folder

Follow the instructions shown at the end of the installation to also be able to conveniently open Morpheus.app from the ‘Applications’ folder. Depending on your processor architecture, Homebrew will install Morpheus in the folder /opt/homebrew/opt/morpheus (ARM) or /usr/local (Intel) by default (according to the so-called Homebrew prefix). Correspondingly, Homebrew will tell you at the end of the installation whether you need to enter either command

ln -sf /opt/homebrew/opt/morpheus/Morpheus.app /Applications

or

ln -sf /usr/local/opt/morpheus/Morpheus.app /Applications

to create a link to Morpheus.app in the Mac’s app folder.

If you want to add Morpheus.app to the Mac app folder at a later point and don’t know your system’s Homebrew path, you can enter the command

ln -sf $(brew --prefix)/opt/morpheus/Morpheus.app /Applications

which will automatically add the correct path and create the link.

The link created in this way in the app folder works independently of the Morpheus version and therefore does not have to be created again for later updates.

Alternatively, you can start Morpheus once in the terminal with

morpheus-gui

and drag the app icon in the dock to your apps on the left, which will create a permanent icon. Note, however, that with this variant the shortcut becomes invalid with every change of the Morpheus version, as it points to a specific Morpheus release and therefore a new shortcut must be created each time.

Open Morpheus

Start morpheus from the command line by typing:

morpheus-gui

Or if set up, via the Morpheus.app link under /Applications.

Update Morpheus

Check for updates and install the latest version of Morpheus with:

brew upgrade morpheus

Or upgrade all Homebrew packages including Morpheus:

brew upgrade

If you just want to check if there is a Morpheus release available without touching your current Morpheus installation, type:

brew update
brew outdated

Uninstall Morpheus

Uninstall Morpheus with the command:

brew uninstall morpheus

If existing, delete the link Morpheus.app in /Applications manually.

Install Other Morpheus Versions

Beta and Development Versions

Also, there is the possibility to install further Morpheus versions that are primarily intended for testing and development purposes:

  • morpheus-beta: all tagged versions such as betas and release candidates,
  • morpheus-release: current development state of the next Morpheus release.

Special Morpheus versions are not included in the standard Morpheus Homebrew tap. To be offered these versions, the morpheus-versions tap must first be added:

brew tap morpheus-lab/morpheus-versions
These Morpheus versions are explicitly not recommended for regular use and may contain bugs or instabilities!

morpheus-beta also includes the stable versions, providing it is the latest version available at the moment of the installation or upgrade:

brew install morpheus-beta
If you already have another version of Morpheus installed, please read the following notes on how to activate the side-by-side installed version and how to switch between versions.

morpheus-release, on the other hand, reflects the current state of the source code and is subject to more frequent changes, some of which have not yet been thoroughly tested:

export HOMEBREW_NO_INSTALL_FROM_API=1
brew install --HEAD morpheus-release
Make sure to set the HOMEBREW_NO_INSTALL_FROM_API variable and pass the --HEAD flag here to install the latest head revision of Morpheus' Git development branch.

Since it is not possible to determine whether an update is available for a development version due to the lack of a version number, to upgrade, instead of brew upgrade, use the command

export HOMEBREW_NO_INSTALL_FROM_API=1
brew uninstall morpheus-release && brew install --HEAD morpheus-release

to reinstall morpheus-release using the latest available source code revision.

Previous Releases

With the Morpheus 2.2.6 release, we introduced the Homebrew package manager for installation on macOS. Starting with this version, it is also possible to conveniently install and run different Morpheus releases in parallel with Homebrew.

Since previous Morpheus releases are not included in the standard Morpheus Homebrew tap (morpheus-lab/morpheus), these versions require additional installation of the morpheus-versions tap:

brew tap morpheus-lab/morpheus-versions

The desired Morpheus version is denoted by the suffix @<MORPHEUS-RELEASE>:

brew install morpheus@<MORPHEUS-RELEASE>

Switch between the installed versions with:

brew link --overwrite morpheus(@<MORPHEUS-RELEASE>)

If you now e.g. click on Morpheus.app or type morpheus-gui, the respective release will be opened.

For example, you could switch back and forth between the latest release (morpheus) and the version 2.2.6 (morpheus@2.2.6) with the commands:

brew link --overwrite morpheus
brew link --overwrite morpheus@2.2.6

For more information, see also the following section ‘Switching between Versions’ in this FAQ.

Switching between Versions

If you have several versions of Morpheus installed in parallel via Homebrew, you must tell Homebrew which installation to default to when starting the GUI with morpheus-gui, the simulator via the command-line interface (CLI) with morpheus or when opening Morpheus.app.

If, for example, you have installed the stable version of Morpheus with brew install morpheus and in parallel also the beta version with brew install morpheus-beta, you have to tell Homebrew with

brew link --overwrite morpheus-beta

before opening Morpheus that morpheus-beta and not morpheus should be loaded. Simply switch back and forth with the command brew link --overwrite <MORPHEUS-VERSION> and then launch the pre-selected Morpheus installation.

Use the brew search command to get an overview of available Morpheus versions. All versions installed on your system are marked with a tick:

➜  ~ brew search morpheus
==> Formulae
morpheus ✔            morpheus-beta ✔

==> Casks morpheus-beta morpheus morpheus-beta220rc1 morpheus201 morpheus220 morpheus223 morpheus2251 macmorpheus morpheus-beta220b3 morpheus121 morpheus210 morpheus222 morpheus224 morpheus2252 ➜ ~

Retrieve details about a specific Morpheus version with the brew info command:

➜  ~ brew info morpheus
Warning: Treating morpheus as a formula. For the cask, use homebrew/cask/morpheus
morpheus-lab/morpheus/morpheus: stable 2.2.6 (bottled)
Modelling environment for multi-cellular systems biology
https://morpheus.gitlab.io/
/opt/homebrew/Cellar/morpheus/2.2.6 (15 files, 13.8MB) *
  Poured from bottle on 2021-11-25 at 23:51:17
From: https://github.com/morpheus-lab/homebrew-morpheus/blob/HEAD/Formula/morpheus.rb
License: BSD-3-Clause
==> Dependencies
Build: boost ✔, cmake ✔, doxygen ✔
Required: ffmpeg ✔, gnuplot ✔, graphviz ✔, libomp ✔, libtiff ✔, qt@5 ✔
==> Caveats
To start the Morpheus GUI, type the following command:

morpheus-gui

Or add Morpheus to your Applications folder with:

ln -sf /opt/homebrew/opt/morpheus/Morpheus.app /Applications ➜ ~

Morpheus on macOS 10.15 ‘Catalina’

The external Homebrew project used by Morpheus to deliver up-to-date Morpheus releases to the users has stopped supporting macOS 10.15 ‘Catalina’ (first introduced by Apple in 2019) in the fall of 2022. Since then, a user with macOS 10.15 ‘Catalina’ doesn’t get precompiled packages, but has to compile all dependencies of Morpheus individually, which can be very tedious and time-consuming.

We strongly recommend to update macOS to one of the newer supported OS versions (macOS 12 ‘Monterey’, macOS 13 ‘Ventura’, macOS 14 ‘Sonoma’ …) to regularly receive Morpheus and its updates for macOS as stress-free as possible and with minimal time and effort.

Nevertheless, we offer two alternative options to install Morpheus on macOS 10.15 ‘Catalina’: via a Homebrew rewind (recommended) or via a DMG file.

As of now, although not officially supported by Homebrew, older versions of precompiled Morpheus dependencies (‘bottles’) are still available directly from Homebrew. You can get them by rolling back the local Homebrew installation on your machine to the fall of 2022 by typing:

git -C $(brew --repo homebrew/core) checkout fbb71d2e7b5

Following this, any Morpheus version can be installed as usual, with the only difference that prefixing HOMEBREW_NO_AUTO_UPDATE=1 and HOMEBREW_NO_INSTALL_FROM_API=1 is required to prevent Homebrew from attempting to obtain the latest versions of the dependencies:

HOMEBREW_NO_AUTO_UPDATE=1 HOMEBREW_NO_INSTALL_FROM_API=1 brew install morpheus

Also prepend or export the environment variables HOMEBREW_NO_AUTO_UPDATE=1 and HOMEBREW_NO_INSTALL_FROM_API=1 in the same way to upgrade an existing Morpheus installation under macOS 10.15 Catalina:

export HOMEBREW_NO_AUTO_UPDATE=1
export HOMEBREW_NO_INSTALL_FROM_API=1
brew upgrade morpheus

DMG File

Another method, which, unlike the Homebrew rewind procedure, may not be available immediately upon the release of a new version of Morpheus, is to download the latest available Apple disk image for Morpheus:

Morpheus-2.3.4.catalina.dmg

When opened, the disk image is mounted as a volume within the Finder. Drag and drop Morpheus.app into your ‘Applications’ folder, then Control-click (do not double-click) the App file inside your ‘Applications’ folder. Select ‘Open’ in the dialog that appears the first time you run it, and you’re ready to go.

Please note that the provided DMG file is only intended to be used on macOS 10.15 ‘Catalina’ and may or may not work on other operating systems. If you’re using a newer OS, please refer to the standard Homebrew installation procedure above.