Getting Started

Quick Start

pip3 install merlin

All set up? See the Merlin Commands section for using merlin.

Check out the Tutorial!

Developer Setup

The developer setup can be done via pip or via make. This section will cover how to do both.

Additionally, there is an alternative method to setup merlin on supercomputers. See the Spack section for more details.

Pip Setup

To install with the additional developer dependencies, use:

pip3 install "merlin[dev]"


pip3 install -e "git+[dev]"

Make Setup

Visit the Merlin repository on github. Create a fork of the repo and clone it onto your system.

Change directories into the merlin repo:

$ cd merlin/

Install Merlin with the developer dependencies:

$ make install-dev

This will create a virtualenv, start it, and install Merlin and it’s dependencies for you.

More documentation about using Virtualenvs with Merlin can be found at Using Virtualenvs with Merlin.

We can make sure it’s installed by running:

$ merlin --version

If you don’t see a version number, you may need to restart your virtualenv and try again.

Configuring Merlin

Once Merlin has been installed, the installation needs to be configured. Documentation for merlin configuration is in the Configuring Merlin section.

That’s it. To start running Merlin see the Merlin Workflows.

(Optional) Testing Merlin


With python 3.6 you may see some tests fail and a unicode error presented. To fix this, you need to reset the LC_ALL environment variable to en_US.utf8.

If you have make installed and the Merlin repository cloned, you can run the test suite provided in the Makefile by running:

$ make tests

This will run both the unit tests suite and the end-to-end tests suite.

If you’d just like to run the unit tests you can run:

$ make unit-tests

Similarly, if you’d just like to run the end-to-end tests you can run:

$ make e2e-tests

Custom Setup

This section documents how to install Merlin without using the Makefile. This setup is more complicated; however, allows for more customization of the setup configurations.

Clone the Merlin repository:

git clone

Create a virtualenv

Merlin uses virtualenvs to manage package dependencies which can be installed via Pip, Python’s default package manager.

More documentation about using Virtualenvs with Merlin can be found at Using Virtualenvs with Merlin.

To create a new virtualenv and activate it:

$ python3 -m venv venv_merlin_$SYS_TYPE_py3_6
$ source venv_merlin_$SYS_TYPE_py3/bin/activate  # Or activate.csh for .cshrc

Install Python Package Dependencies

Merlin uses Pip to manage Python dependencies. Merlin dependencies can be found in the requirements directory in the Merlin repository.

To install the standard set of dependencies run:

(merlin3_7) $ pip install -r requirements.txt

This will install all the required dependencies for Merlin and development development dependencies.

Installing Merlin

Merlin can be installed in editable mode. From within the Merlin repository:

(merlin3_7) $ pip install -e .

Any changes made to the Merlin source code should automatically reflect in the virtualenv.


If changes to Merlin’s source code do not reflect when running Merlin try running pip install -e . from within the Merlin repository.