| News and Announcements » |
QIIME consists of native python code and additionally wraps many external applications. This gives the user flexibility to easily build their own analysis pipelines, making use of popular microbial community analysis tools. QIIME handles the processing of input and output of these applications, so the user can spend time analyzing their data rather than parsing, writing, and converting file formats.
As a consequence of this pipeline architecture, QIIME has a lot of dependencies and can (but doesn’t have to) be very challenging to install.
We therefore break this guide down into several parts:
- First we tell you how you can avoid installing QIIME natively, and instead use pre-built virtual machines or MacQIIME.
- Then we show how to install QIIME natively with a minimal (base) install. This is easy, and is sufficient for the vast majority of users.
- Finally, we cover how to install QIIME natively doing a complete install. This can be very challenging, and is likely only needed by users looking to develop custom analysis workflows.
Since QIIME can be difficult to install, we have attempted to shift this burden away from our users by providing the following options:
- MacQIIME: The easiest way to get a complete, native QIIME base install (and a nearly complete full install) for Mac OS X. MacQIIME is built and maintained by the Werner Lab.
- QIIME Virtual Box: A virtual machine that you run on your own hardware.
- QIIME Amazon Web Services virtual machine: A virtual machine that you run on rented hardware.
We highly recommend going with one of these options if you’re new to QIIME, or just want to test it out to see if it will do what you want.
If you want to customize QIIME, work with QIIME in a multi-user environment (e.g., a Linux cluster), are interested in getting involved in QIIME development, or want to use the development version of QIIME, you may need to install QIIME manually.
For the vast majority of use cases, the QIIME minimal (base) install will be sufficient. This is much easier than a QIIME full install. Additionally, it’s possible to add parts of the QIIME full install to an existing QIIME base install as needed, so the QIIME base install is nearly always what you should do to get started.
The QIIME base install allows use of core QIIME functionality, including, but not limited to:
First, you need to have a build environment on your machine:
On OS X, this involves installing the developer tools.
On Debian-based Linux (e.g., Ubuntu), this involves installing the following packages:
sudo apt-get install build-essential python-dev python-pip
Warning
Depending on your system, additional packages may need to be installed that may be required by QIIME or its dependencies. Also, packages names will vary across operating systems and even within operating system distributions (e.g., different versions of Ubuntu). Since there are a wide range of systems that QIIME can be installed on, the QIIME development team cannot provide a comprehensive list of commands that are guaranteed to successfully install QIIME on your system.
If you encounter problems installing QIIME, please visit http://help.qiime.org.
The easiest way to install the latest QIIME release and its base dependencies is with pip:
pip install numpy
pip install qiime
If you do not have pip, the easiest way to install it is by running:
easy_install pip
Or, if you are on Ubuntu, run:
apt-get install python-pip
Note: You may need to prefix the above commands with sudo if you do not have permission to place files in the default locations. You will also need an active Internet connection.
These commands install QIIME and all of its Python dependencies. pip install qiime will also attempt to install some non-Python dependencies, including uclust, FastTree, SortMeRNA, SUMACLUST, and swarm. If any of the non-Python dependencies cannot be installed, they will be skipped and you’ll need to install them manually if you need to use them. See below for links to where you can obtain these dependencies if any of them fail to install with pip.
If you don’t have permission (or don’t want) to install QIIME into your system (e.g., with sudo), you might want to look into these alternatives:
- Anaconda
- virtualenv and virtualenv-wrapper (this is what most of the QIIME developers use instead of system-wide QIIME installations)
- Canopy
- pip-install to a non-system directory
After installing the QIIME base packages, you can test the installation:
print_qiime_config.py -t
If the output doesn’t indicate any failures, you’re now ready to use QIIME. If you’re working in a cluster environment, you may next want to make some customizations by setting up your qiime config file. You should also read the documentation on using parallel qiime.
You should begin by performing the QIIME minimal (base) install. The following steps are not necessary for the vast majority of QIIME’s use cases.
Then, install the following packages. If you’re installing on Linux, the easiest way to install most of these packages is using qiime-deploy.
Alternatively, you can manually install some or all of the following packages. These are grouped by the features that each dependency will provide access to. Installation instructions should be followed for each individual package (e.g., from the project’s website or README/INSTALL file).
Alignment, tree-building, taxonomy assignment, OTU picking, and other data generation steps:
Processing sff files:
Denoising 454 data:
Network visualization:
Advanced statistics, including those performed in supervised_learning.py, detrend.py and compare_categories.py:
If you plan to use SourceTracker with QIIME:
For joining paired end reads, with join_paired_ends.py and multiple_join_paired_ends.py:
For improved performance with large BIOM files, or if you’re working with BIOM format 2.x files (see here for more details):
After installing the packages above, you can test this for sanity by running:
print_qiime_config.py -tf
If the output doesn’t indicate any failures related to packages that you plan to use, you’re now ready to use QIIME. If you’re working in a cluster environment, you may next want to make some customizations by setting up your qiime config file. You should also read the documentation on using parallel qiime.
Due to size constraints, pip-installing QIIME won’t download QIIME’s unit tests. If you want to run QIIME’s comprehensive unit test suite after installing QIIME, you should download the QIIME source code from GitHub for the version of QIIME that you’ve installed. After unpacking the source distribution, you should run the test suite. Execute the following commands:
cd qiime-<version>/tests/
python all_tests.py
Where qiime-<version> will be dependent on the specific version that you’ve downloaded.
You will see test output on the terminal indicating test successes and failures. Some failures are OK.
The all_tests.py command will complete with a summary of test failures. Some tests may fail due to missing external applications – these will be noted separately from other test failures. If these are related to features of QIIME that you are not using, this is acceptable. Otherwise, you’ll want to ensure that you have the external applications installed correctly (be sure to check that you have the right versions, QIIME may not always work with the latest version of an external dependency), and re-run the tests.
We have attempted to provide accurate licensing information for the above dependencies for the convenience of our users. This information is by no means definitive and may contain errors. Any questions about licenses or the legality of specific uses of these software packages should be directed to the authors of the software. Do not rely solely on the license information presented above!
External applications used by QIIME need to be visible to the shell by existing in the executable search path (i.e., listed in the $PATH environment variable). For example, if you plan to use cd-hit, and have the cd-hit executables installed in $HOME/bin you can add this directory to your system path with the commands:
echo "export PATH=$HOME/bin/:$PATH" >> $HOME/.bashrc
source $HOME/.bashrc
If you plan to use the RDP classifier for taxonomy assignment you must define an RDP_JAR_PATH environment variable. If you downloaded and unzipped the RDP classifier folder in $HOME/app/, you can do this with the following commands:
echo "export RDP_JAR_PATH=$HOME/app/rdp_classifier_2.2/rdp_classifier-2.2.jar" >> $HOME/.bashrc
source $HOME/.bashrc
Note that you will need the contents inside rdp_classifier_2.2 for the program to function properly.
The uclust binary must be called uclust, which differs from the names of the posted binaries, but is the name of the binary if you build from source. If you’ve installed the binary uclust1.2.21q_i86linux64 as $HOME/bin/uclust1.2.21q_i86linux64, we recommend creating a symbolic link to this file:
ln -s $HOME/bin/uclust1.2.21q_i86linux64 $HOME/bin/uclust
The usearch binary must be called usearch, which differs from the names of the posted binaries, but is the name of the binary if you build from source. If you’ve installed the binary usearch5.2.236_i86linux32 as $HOME/bin/usearch5.2.236_i86linux32, we recommend creating a symbolic link to this file:
ln -s $HOME/bin/usearch5.2.236_i86linux32 $HOME/bin/usearch
ChimeraSlayer can only be run from the directory where it was unpacked and built as it depends on several of its dependencies being in specific places relative to the executable (ChimeraSlayer/ChimeraSlayer.pl). Carefully follow the ChimeraSlayer install instructions. Then add the directory containing ChimeraSlayer.pl to your $PATH environment variable. If your ChimeraSlayer folder is in $HOME/app/ you can set the $PATH environment variable as follows:
echo "export PATH=$HOME/app/ChimeraSlayer:$PATH" >> $HOME/.bashrc
source $HOME/.bashrc
If you’re having trouble getting ChimeraSlayer to work via QIIME, you should first check to see if you can run it directly from a directory other than its install directory. For example, try running ChimeraSlayer.pl from your home directory.
Once you have configured Qiime, you can test your ChimeraSlayer install by running:
print_qiime_config.py -tf
This includes a check for obvious problems with your ChimeraSlayer install, and should help you determine if you have it installed correctly.
To install R visit http://www.r-project.org/ and follow the install instructions. Once R is installed, run R and execute the following commands:
install.packages(c('ape', 'biom', 'optparse', 'RColorBrewer', 'randomForest', 'vegan'))
source('http://bioconductor.org/biocLite.R')
biocLite(c('DESeq2', 'metagenomeSeq'))
q()
AmpliconNoise requires that several environment variables are set. After you’ve installed AmpliconNoise, you can set these with the following commands (assuming your AmpliconNoise install directory is $HOME/AmpliconNoiseV1.27/):
echo "export PATH=$HOME/AmpliconNoiseV1.27/Scripts:$HOME/AmpliconNoiseV1.27/bin:$PATH" >> $HOME/.bashrc
echo "export PYRO_LOOKUP_FILE=$HOME/AmpliconNoiseV1.27/Data/LookUp_E123.dat" >> $HOME/.bashrc
echo "export SEQ_LOOKUP_FILE=$HOME/AmpliconNoiseV1.27/Data/Tran.dat" >> $HOME/.bashrc
If you do not install QIIME using setup.py and you plan to use the QIIME Denoiser, you’ll need to compile the FlowgramAlignment program. To do this you’ll need to have ghc installed. Then from the Qiime/qiime/support_files/denoiser/FlowgramAlignment/ directory, run the following command:
make ; make install
