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 https://raw.githubusercontent.com/Homebrew/install/master/install)"
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
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 http://huttenhower.sph.harvard.edu/metaphlan2_downloads/metaphlan2-2.6.0.tar.gz 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 folder in your User directory). It’s probably a file called
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
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 biobakery-metaphlan2-7df8753d7e5e.zip
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
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
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
nano, a text editor in the terminal. Copy/paste the full
command above into the file, and then hit
ctrl+x to exit, and
y to save your
$ 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).
- 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
- 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 brewshould return something like
/usr/local/bin/brew). Otherwise, there will be no output and you’ll just go back to the command line. ^
- 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. ^
- If you don’t have pip (check with
which pip), check out https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py ^