Quickstart¶
This guide describes how to install and set up a QIIME 2 development environment.
Note
QIIME 2 does not currently support installation on Windows.
Install Prerequisites¶
Miniconda provides the conda environment and package manager, and is the recommended way to install QIIME 2. Follow the instructions for downloading and installing Miniconda. You may choose either Miniconda2 or Miniconda3 (i.e. Miniconda Python 2 or 3). QIIME 2 will work with either version of Miniconda.
After installing Miniconda and opening a new terminal, make sure you’re running the latest version of conda (and get a copy of wget, while you’re at it):
conda update conda
conda install wget
Install QIIME 2 within a conda environment¶
Once you have Miniconda installed, create a conda environment and install the latest QIIME 2 staging distribution within the environment. We highly recommend creating a new environment specifically for development purposes. You can choose whatever name you’d like for the environment. In this example, we’ll name the environment qiime2-dev.
Please choose the installation instructions that are appropriate for your platform (macOS vs Linux).
macOS¶
wget https://raw.githubusercontent.com/qiime2/environment-files/master/latest/staging/qiime2-latest-py38-osx-conda.yml
conda env create -n qiime2-dev --file qiime2-latest-py38-osx-conda.yml
rm qiime2-latest-py38-osx-conda.yml
Linux¶
wget https://raw.githubusercontent.com/qiime2/environment-files/master/latest/staging/qiime2-latest-py38-linux-conda.yml
conda env create -n qiime2-dev --file qiime2-latest-py38-linux-conda.yml
rm qiime2-latest-py38-linux-conda.yml
Activate the conda environment¶
conda activate qiime2-dev
# to deactivate:
# conda deactivate
qiime info
The output from qiime info should indicate that you have development versions of the QIIME 2 packages installed (the displayed versions will differ):
Next steps¶
If you want to make changes to the framework, q2cli, or any of the official plugins, check out the steps involved in the following example (for the sake of this example, we will focus on developing q2-taxa):
# Grab the package source from the relevant source repository.
git clone https://github.com/qiime2/q2-taxa
cd q2-taxa
# Install any additional build-time dependencies needed for this project.
# Check ci/recipe/meta.yaml in any official QIIME 2 repository for build requirements.
conda install nodejs pytest flake8
# Install local source in "development mode", and build any package assets.
make dev
# Run package tests to ensure that everything is okay.
make test
Congratulations! You should now have a working development environment - time to start hacking!
