Create your plugin from a template#

The easiest way to create a new QIIME 2 plugin is using our Cookiecutter template, which can be found at caporaso-lab/cookiecutter-qiime2-plugin. Here we’ll work through building your QIIME 2 plugin from this template.

Install the tools needed for templating your plugin#

To start building your new plugin, first install cookiecutter using their installation instructions. (If you opt to install cookiecutter with pipx, which the cookiecutter developers recommend, you can find the pipx installation instructions here.)

Run cookiecutter to create your plugin#

Next, run cookiecutter to create your plugin from the template using the following command. If you used pipx to install cookiecutter, follow the instructions in the pipx tab - otherwise follow the instructions in the Other tab.

pipx run cookiecutter gh:caporaso-lab/cookiecutter-qiime2-plugin
cookiecutter gh:caporaso-lab/cookiecutter-qiime2-plugin

During the plugin templating process, you’ll be prompted for information on your new plugin. For the questions about the Target distribution and whether you’re targeting the stable or latest development QIIME 2 release, use the default values unless you have a specific reason not to; these are the last two questions, as of this writing in May 2024. For all of the other questions, feel free to customize your plugin by providing whatever values you’d like.

The plugin I’m going to create will be called q2-dwq2 (for Developing with QIIME 2). After you’ve answered all of the questions, your plugin should have been successfully created and be ready to be installed and used.


If you’d like to learn more about the files that were created in this process, you can refer to The structure of QIIME 2 plugin packages. You don’t need to know what all of these files are to continue the tutorial though, so you can also come back to that later.

Install and test your new plugin#

After the plugin has been created, change into the top-level directory for the plugin. For me, that’s q2-dwq2/. In that directory, you’ll find a file called, which has a section in it containing Installation instructions. Follow all of the installation instructions, and then follow the instructions in that file for testing and using your new plugin.

After completing all of those steps, you now have a QIIME 2 deployment on your computer that includes your new plugin. When you requested help text on your plugin (e.g., qiime dwq2 --help), you should have seen some of the information you provided when creating the plugin.

The template plugin includes a simple (and silly) action called duplicate-table, along with associated unit tests. This provides an example action and example unit tests. You’ll ultimately want to delete this action, but for now let’s use it to make sure everything is working as expected.

Call your plugin’s duplicate-table action with the --help parameter (e.g., qiime dwq2 duplicate-table --help). You should see text that looks like the following:

Usage: qiime dwq2 duplicate-table [OPTIONS]

  Create a copy of a feature table with a new uuid. This is for demonstration
  purposes only. 🧐

  --i-table ARTIFACT FeatureTable[Frequency]
                          The feature table to be duplicated.       [required]
  --o-new-table ARTIFACT FeatureTable[Frequency]
                          The duplicated feature table.             [required]
  --output-dir PATH       Output unspecified results to a directory
  --verbose / --quiet     Display verbose output to stdout and/or stderr
                          during execution of this action. Or silence output
                          if execution is successful (silence is golden).
  --example-data PATH     Write example data and exit.
  --citations             Show citations and exit.
  --help                  Show this message and exit.

If you’d like to try the action out, you can call your duplicate-table action on any QIIME 2 FeatureTable[Frequency] artifact (e.g., you can download one from the QIIME 2 user documentation). Load your duplicated table with QIIME 2 View, and poke through its Provenance to see how data provenance is recorded for your plugin.

Congratulations - you’ve created a working QIIME 2 plugin from a template! If you’d like to learn QIIME 2 plugin development, in the next step of the tutorial we’ll Add a first (real) Method. If you’re already comfortable with QIIME 2 plugin development, you’re all set to make this plugin your own. In either case, if you’d like to host your plugin in a GitHub repository, you can refer to Distribute plugins on GitHub.


You can see my code after following these steps by looking at the specific commit in my plugin repository on GitHub: caporaso-lab/q2-dwq2. My code may look a little different than yours as I may have been using an older version of the template plugin than you used - everything in the tutorial will still work the same though.