Installing the Biobakery on Mac


This is a post written for students of BISC314 at Wellesley, but may be relevant for anyone else attempting to install the biobakery on a Mac. As of this writing, the homebrew recipes for installing several of the modules aren’t actually working on mac, so read on for some other options.

The biobakery is a suite of microbiome and metagenomics analysis tools developed by the Huttenhower lab at Harvard School of Public Health. Most of them are python-based, and run at the command line. Installation should be relatively straightforward, but I and some students ran into some problems a couple of weeks ago. See below for more details about the software (HUMAnN2 and MetaPhlAn)

Install MetaPhlAn2 with Homebrew

Homebrew should be the easiest way to get these tools installed. If you haven’t installed homebrew before, the following command should install it onto your system:

$ /usr/bin/ruby -e "$(curl -fsSL"

If you go to that website, what you’re looking at is a bunch of code written in the programming language Ruby (in other words, a ruby “script”). This command tells your computer to use ruby to interpret the text (essentially running the ruby script). Another option would be to copy the text from that website into a file called install_brew.rb1, and then running:

$ ruby -e install_brew.rb

Be sure you’re in the same directory as the file you saved, or use the absolute path (eg ~/Desktop/install_brew.rb)

If neither of the above options work, google around with the errors you’re getting, and see if the internet has any advice that will help. Otherwise, skip ahead.

If that worked, or if you already have homebrew installed2, first tap the biobakery, then install metaphlan2:

$ brew tap biobakery/biobakery
$ brew install metaphlan2
==> Installing metaphlan2 from biobakery/biobakery
==> Downloading
Already downloaded: /Users/kev/Library/Caches/Homebrew/metaphlan2-2.6.0.tar.gz
Please install python2

If you get the same message, it didn’t work. Skip ahead to try the other way.

Install MetaPhlAn2 from source

If homebrew didn’t work for you above, welcome to programming! Everything will be ok, just grab your towel and don’t panic.

The first thing to do is to download the zip file containing all of the code. To do so, click this link. You can download it anywhere you like, but for the rest of this, I’m going to assume you downloaded it into ~/Downloads (ie the Downloads folder in your User directory). It’s probably a file called something like

First, you want to unpack it - this converts the zip file into a folder that contains a bunch of files. If you double-click the zip file in Finder, it will automatically unpack into the same folder. In other words, you’ll now have a folder at ~/Downloads/biobakery-metaphlan2-7df8753d7e5e/.

Alternatively, you can do this from the command line. Assuming you’ve navigated to your Downloads folder (or wherever you downloaded the zip file to):

$ tar xzvf

Either way, you now have a folder containing all the code, great! The trouble is, I routinely clear out my downloads folder, so it’s a good idea to move it somewhere a bit more stable. I have folder organization that suits me personally, but you can move it anywhere you like. You may also want to rename it while you’re at it:

$ mv ~/Downloads/biobakery-metaphlan2-7df8753d7e5e ~/metaphlan2

You can also do this by dragging/dropping and then manually renaming it in finder, but remember that all of this stuff gets easier the more you practice. And I promise, even if it seems slower now, it gets way easier and ultimately more comfortable to do things this way.

Anyway, assuming you now have a metaphlan2 folder somewhere, you now need to tell the command line to look for that folder whenever you’re calling scripts from the command line.

To do this, you have to edit a variable called PATH. PATH is already defined, which you can see if you run the command echo $PATH. You should see something like:


Where a list of paths to various software exectables are found, separated by :. To add your new metaphlan folder to this variable, enter:

$ export PATH=~/metaphlan2:~/metaphlan2/utils:$PATH

This says, make the PATH variable equal to ~/metaphlan2 (where the folder is) as well as the underlying utils folder, then append what’s currently in the PATH variable (what you saw with echo) already.

However, this only works for your current terminal session (if you quit and start again, you’d have to do this each time). To permanently set your terminal to look for this folder, you can edit a file called ~/.bash_profile to add the line above. This file is run every time you start a termnial session. You can edit this in a normal text editor (though it’s hidden by default - you can press cmd+shift+. in finder to see it), or use a terminal text editor.

$ nano ~/.bash_profile

This opens nano, a text editor in the terminal. Copy/paste the full export command above into the file, and then hit ctrl+x to exit, and y to save your changes.

Install Dependencies

Unfortunately, we’re not done yet. We now have to install MetaPhlAn2’s dependencies 3. Some of these can be installed with homebrew, and hopefully will not have the same issues as with metaphlan.

$ brew tap brewsci/bio
$ brew install bowtie2
$ brew install numpy

The rest can be installed with the python package manager, pip4. First, update pip, then install the packages:

$ pip install --upgrade pip
$ pip install pandas
$ pip install biopython
$ pip install matplotlib

Install HUMAnN2 with pip

$ pip install humann2

Should work just fine. To do real analyses, you need to download a referance database. But there’s a smaller version that will work for this demo:

$ humann2_databases --download chocophlan DEMO humann2_database_downloads

When it comes time to work with cheese metagenomes, you’ll need the full (much larger) database:

$ humann2humann2_databases --download chocophlan full humann2_database_downloads

There are also a bunch of demo inputs/outputs that can be found here (it’s a good idea to read through the tutorial before class anyway).

  1. The name of the file doesn’t actually matter, it’s just convnetion to name scripts based on the programming language that runs them. A ruby script is usually .rb, a python file is usually .py etc. ^
  2. you can test whether software is installed by typing which <software> at the command line, which should return an absolute path if the software is found (eg which brew should return something like /usr/local/bin/brew). Otherwise, there will be no output and you’ll just go back to the command line. ^
  3. These are pieces of software that MetaPhlAn2 depends on to run. Most software has dependencies - there’s no reason to re-write code that someone else wrote if you can just use their software instead. When you install with homebrew, it takes care of dependencies for you. ^
  4. If you don’t have pip (check with which pip), check out ^