Developing with QIIME 2

Developing with QIIME 2#

Your guide for writing, testing, and distributing QIIME 2 plugins, interfaces, and documentation.

Development status of this content

Developing with QIIME 2 remains in very active development, and as a result some URLs may change. It should be getting more complete by the day. 🚀

The canonical URL for this project is now

The “old developer documentation”, which was previously hosted at, is now deprecated. All content that is still relevant has been ported from that documentation to Developing with QIIME 2. If you want to access that archival content, you can find it in the project’s GitHub repository.

The Tutorial: A step-by-step guide to building your first QIIME 2 plugin chapter is where the focus is for the near future, though all of the Plugin Development chapters have useful and up-to-date content in them. You’ll also find content in Explanations and various other chapters throughout, but those are currently less thorough and generally need some updates. Please let us know if you find anything that is inaccurate or outdated.

Developing with QIIME 2 (DWQ2) is split into multiple Parts covering topics in QIIME 2 development, including Plugin Development, Interface Development, and Docs Development. You do not need to read all of these parts to develop with QIIME 2. If you are interested in creating plugins, then the only part you need to concern yourself with is Plugin Development. Similarly, if you want to build an interface, you only need Interface Development. Other parts, such as Framework Development and Distribution Development, are currently targeted primarily for the development team in the Caporaso Lab. Docs Development is slated for a full re-write as we adapt our approach to user documentation.

The content in each part of this book is organized under the Diátaxis framework [1]. This means that you can expect Chapters containing Tutorials, How-To-Guides, Explanations, and References in each part. Each serves a different goal for the reader:




Provide a guided exploration of a topic for learning.

How To Guides

Provide step-by-step instructions on how to accomplish specific goals.


Provide a discussion intended to aid in understanding a specific topic.


Provide specific information (e.g., an API reference).

Chapters are generally broken up into Sections. For example, the Tutorial: A step-by-step guide to building your first QIIME 2 plugin chapter works through building a new QIIME 2 plugin from scratch. It does this in a series of sections that focus on different plugin components.


The authors would like to thank those who have contributed to the writing of Developing with QIIME 2.

The template plugin used in Tutorial: A step-by-step guide to building your first QIIME 2 plugin was derived from @misialq’s plugin template.

Getting Help#

For the most up-to-date information on how to get help with QIIME 2, as a user or developer, see here.


To get information on contributing to Developing with QIIME 2, see Developer documentation.


This work was funded in part by NIH National Cancer Institute Informatics Technology for Cancer Research grant 1U24CA248454-01, and by grant DAF2019-207342 from the Chan Zuckerberg Initiative (CZI) DAF, an advised fund of Silicon Valley Community Foundation (CZI grant DOI: 10.37921/862772dbrrej; funder DOI 10.13039/100014989).

This book is built with MyST Markdown and Jupyter Book, which are supported in part with funding from the Alfred P. Sloan Foundation.

Initial support for the development of QIIME 2 was provided through a grant from the National Science Foundation.


Developing with QIIME 2 (DWQ2) by Greg Caporaso and Evan Bolyen is made available under the CC BY-NC-ND 4.0 license.

The QIIME 2 plugin cookiecutter template is made available under the BSD 3-Clause license. Unlike DWQ2, derivative works of that template are allowed (i.e., you can build real plugins that you intend to distribute for any purpose, including commercial, from the template).