Microbial 'omics

Brought to you by

Table of Contents

The latest version of anvi’o is v5.5. See the release notes.

This article explains basic steps of installing anvi’o using rather conventional methods.

Please consider opening an issue for technical problems, or join us on Slack if you need help:

Questions? Concerns? Find us on

A note on Chrome

Currently, the Chrome Web Browser has the most efficient SVG engine among all browsers we tested. For instance, Safari can run the anvi’o interactive interface, however it takes orders of magnitude more time and memory compared to Chrome. Firefox, on the other hand, doesn’t even bother drawing anything at all. Long story short, the anvi’o interactive interface will not perform optimally with anything but Chrome. So you need Chrome. Moreover, if Chrome is not your default browser, every time interactive interface pops up, you will need to copy-paste the address bar into a Chrome window. You can learn what is your default browser by running this command in your terminal:

python -c 'import webbrowser as w; w.open_new("http://")'

Painless installation with Conda

This is a very simple and effective way to install anvi’o on your system along with all of its dependencies (we thank John Eppley for pushing us towards this direction). For this to work, you need miniconda to be installed on your system. If you are not sure whether it is installed or not, open a terminal (hopefully an iTerm if you are using Mac) and type conda. You should see an output like this instead of a ‘command not found’ error (your version might be different):

$ conda --version
conda 4.6.2

If you don’t have conda installed, then you should first install it through their installation page. Once you have confirmed you have conda installed, you are golden.

Run this command to install the latest stable version of anvi’o:

conda install -n anvio5 -c bioconda -c conda-forge anvio=5.5.0

Note that the most up-to-date conda-available anvi’o version, which is currently v5.5, may differ from the most up-to-date stable anvi’o version, which is v5.5 according to our headquarters at Westeros.

If you get an EnvironmentLocationNotFound error from the previous command, try what Bruno Gomez-Gil suggested instead:

conda create -n anvio5 -c bioconda -c conda-forge anvio=5.5.0

Note: One of our users who has been trying conda installation on an HPC system reported the following steps working for them:

conda create -y --name anvio5 python=3.6
conda install -y --name anvio5 -c bioconda -c conda-forge anvio=5.5.0

Once the installation is complete, test anvi’o quickly to make sure everything is in order:

anvi-self-test --suite mini

IMPORTANT NOTE: You may need to activate the anvi’o conda environment every time you open a new terminal window. Depending on your conda setup, you will either need to run source activate anvio5 or conda activate anvio5 (this assumes you named your conda environment for anvio anvio5 as per the commands above using the --name flag –if not, please replace anvio5 with whatever you have used to name your environment).

Installation (with varying levels of pain)

First things first: nothing here is as scary as it looks, and you can do it.

Firs, you will need to make sure your system does have all the following software if you are going to follow any of the following installation instructions. If you just follow these links, you will most probably be golden:

Finally you will need virtualenv. This should work for most:

pip install virtualenv

If you don’t have pip, you will need to visit this web page to have it installed.

Please note, anvi’o uses Python 3 exclusively.

You may run into some issues eith matplotlib in the virtual environment. A simple solution is to use venv (which comes built-in in python 3) instead of virtualenv.

If you run into any trouble, send an e-mail to Google Groups for anvi’o.

OK. If made through the section above, you may have gone through the most painful part already, and anvi’o developers are very proud of you.

Installing the latest stable release (safe mode)

Questions? Concerns? Find us on

This is the best way to install the stable release (but not the best way if you would like to synchronize your anvi’o to the development version, for which you should jump to the ‘active codebase’ section).

You will do everything in a Python virtual environment. If you are not experienced with computer thingies, do not worry. If you have taken care of your dependencies mentioned above, the rest should be very simple.

We first need to create a new virtual environment for anvi’o. Since it is easier to keep all virtual environments in one place, I will first create a directory in my home:

mkdir ~/virtual-envs/

Then we will create a new virtual environment for anvi’o under that directory, to activate it, and to check the Python version in it to make sure the version starts with 3:

virtualenv ~/virtual-envs/anvio-5.5
source ~/virtual-envs/anvio-5.5/bin/activate
python --version

If using venv, run python3 -m venv ~/virtual-envs/anvio-5.5

If using conda, run python3 -m virtualenv ~/virtual-envs/anvio-5.5

The output of the last command must start with Python 3. If not, remove the virtual environment with rm -rf ~/virtual-envs/anvio, and find out how can you create a virtual environment for Python 3 on your system. You can try -p python3 as a parameter to your virtualenv command. Or you can type virtualenv and without pressing the space character press TAB key twice quickly to see if there is an alternative binary such as virtualenv-3.5 or virtualenv-3.5. If not, it means Python 3 is not installed on your system.

Make sure your paths look alright. Yours should look similar to this:

(anvio-5.5) meren ~ $ which pip

A note on Python 3.7

This box is only relevant to you if you are using Python version 3.7. In that case some dependencies will fail to install as their latest stable release is not compatible with this Python version. For these dependencies you need to install development versions.


pip install https://github.com/scikit-learn/scikit-learn/archive/4035e60a6f0a0a2546bf0442ab603961c6a9cc4a.zip

Datrie (Dependency of snakemake)

pip install https://github.com/ozcan/datrie/releases/download/0.7.1/datrie-0.7.1.tar.gz

Or from original source:

wget https://github.com/pytries/datrie/archive/0.7.1.tar.gz
tar xf 0.7.1.tar.gz
cd datrie-0.7.1
python3.7 setup.py build
python3.7 setup.py install

After installing these dependencies you should be able to install anvi’o. But when you run anvi-profile --version. The anvi’o version may show up as vunknown. This happens when the version of an anvi’o depenceny does not match to what anvi’o expects. You can always check the actual version of anvi’o with pip show anvio or pip list | grep anvio.

Now you can do the installation:

pip install numpy
pip install scipy
pip install cython
pip install anvio

If all looks good, now you should be able to run anvi-self-test:

anvi-self-test --suite mini

You may see warning messages during self-test runs. Don’t be concerned.

If this runs successfully, a browser window will popup. Don’t forget to go back to your terminal and press CTRL+C to kill the server. To leave the virtual environment, you can run the command deactivate.

Now every time you want to use anvi’o, you will need to activate the virtual environment. If you like things to be convenient as much as we do, you may want to run the following command so you have a new command, anvi-activate that activates your anvi’o installation:

echo 'alias anvi-activate-v5.5="source ~/virtual-envs/anvio-5.5/bin/activate"' >> ~/.bash_profile

When I open a new terminal, things look like this:

meren ~ $ anvi-interactive -v
-bash: anvi-interactive: command not found
meren ~ $ anvi-activate-v5.5
(anvio) meren ~ $ anvi-interactive -v
Anvi'o version ...............................: 5.5
Profile DB version ...........................: 20
Contigs DB version ...........................: 8
Pan DB version ...............................: 5
Samples information DB version ...............: 2
Genome data storage version ..................: 1
Auxiliary data storage version ...............: 3
Anvi'server users data storage version .......: 1
(anvio) meren ~ $ 

Installing or updating from the active codebase (because why not)

This will allow you to go beyond the stable version and follow the very current version of the codebase (we assume you already have taken of your dependencies).

Let’s setup a new virtual environment and activate it:

virtualenv ~/virtual-envs/anvio-dev
source ~/virtual-envs/anvio-dev/bin/activate
python --version

If using conda, run python3 -m virtualenv ~/virtual-envs/anvio-dev

Don’t forget to make sure the output of the last command starts with Python 3.

I need to get the codebase

So this is your first time with the codebase. Get a fresh copy (with all the submodules necessary):

git clone --recursive https://github.com/meren/anvio.git

Then go into the anvio directory, and then run the installation:

cd anvio
source ~/virtual-envs/anvio-dev/bin/activate
pip install -r requirements.txt
python setup.py install

I already have the codebase

So you want to update your already existing installation. Follow these steps:

cd anvio
git pull
git submodule update --init --recursive
source ~/virtual-envs/anvio-dev/bin/activate
pip install -r requirements.txt
python setup.py install

What now?

Now it is time to run anvi-self-test --suite mini, of course.

If you want to make things simpler, you can add an alias to your ~/.bash_profile to easily switch to this environment:

echo 'alias anvi-activate-dev="source ~/virtual-envs/anvio-dev/bin/activate"' >> ~/.bash_profile

Installation for developers (you’re a wizard, arry)

This is the best option to keep up-to-date with day-to-day updates from anvi’o developers.

If you are planning to do this, you really need no introductions, but I will give you one anyway. Clone the codebase into a $DIR you like:

cd $DIR
git clone --recursive https://github.com/meren/anvio.git

Create a virtual environment (master to remind you that you are following the GitHub master), and do the initial setup, and leave it:

If using conda, run python3 -m virtualenv ~/virtual-envs/anvio-master instead of the line that starts wth virtualenv down below.

virtualenv ~/virtual-envs/anvio-master
source ~/virtual-envs/anvio-master/bin/activate
python --version # make sure the output starts with `Python 3`.
cd $DIR/anvio # don't forget to update the $DIR with the real path
pip install -r requirements.txt
python setup.py build
cp build/lib.*/anvio/*so anvio/
rm -rf anvio.egg-info build dist

Then update your activation batch to add necessary environment variables:

Please note that you need to update the $DIR variable to whichever directory you cloned the codebase on your system before running the following lines in your terminal.

echo 'export PYTHONPATH=$PYTHONPATH:$DIR/anvio/' >> ~/virtual-envs/anvio-master/bin/activate
echo 'export PATH=$PATH:$DIR/anvio/bin:$DIR/anvio/sandbox' >> ~/virtual-envs/anvio-master/bin/activate

That’s it. If you like, add an alias to your ~/.bash_profile to activate this quickly:

echo 'alias anvi-activate-master="source ~/virtual-envs/anvio-master/bin/activate"' >> ~/.bash_profile
source ~/.bash_profile

Finally, if you would like to pull the latest commits from GitHub every time you switch to the master, add these to your activation batch (you will need to update $DIR once again):

echo 'cd $DIR/anvio && git pull && cd -' >> ~/virtual-envs/anvio-master/bin/activate

You are golden.

Running the “Mini Test”

You can make anvi’o test itself by running the program anvi-self-test. It is absolutely normal to see ‘warning’ messages. In most cases anvi’o is talkative, and would like to keep you informed. You should read those warning messages carefully, but they often don’t require any action.

Upon the successful completion of all the tests, your browser should popup and take you to the interactive interface. When you click that ‘Draw’ button whenever you see one. One of those interfaces should look something like this (this is one of the older version of the anvi’o interactive interface, and it shall stay here so we remember where we came from):

All fine? Perfect! Now you have a running installation of anvi’o!

It is time to go through some anvi’o tutorials (see the pull-down menu at the top of this page), or take a look at all the other posts on the platform.