# Learn QIIME 2 with the all-new gut-to-soil tutorial

**URL:** <https://forum.qiime2.org/t/learn-qiime-2-with-the-all-new-gut-to-soil-tutorial/34387>\
**Category:** News\
**Created:** [November 10, 2026, 3:54pm UTC](https://forum.qiime2.org/t/learn-qiime-2-with-the-all-new-gut-to-soil-tutorial/34387 "2026-11-10T15:54:43Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![gregcaporaso](https://forum.qiime2.org/user_avatar/forum.qiime2.org/gregcaporaso/32/17769_2.png) [@gregcaporaso](https://forum.qiime2.org/u/gregcaporaso)\
**Post date:** [November 10, 2026, 3:54pm UTC](https://forum.qiime2.org/t/learn-qiime-2-with-the-all-new-gut-to-soil-tutorial/34387/1 "2026-11-10T15:54:43Z")

</div>

I'm excited to share the all new [_Gut-to-Soil Microbiome Axis Tutorial_](https://amplicon-docs.qiime2.org/en/stable/tutorials/gut-to-soil/), which went live with the [2026.10 release of QIIME 2](https://forum.qiime2.org/t/qiime-2-2026-10-is-now-available/34362). This is intended to be the primary entry point for new QIIME 2 users to learn an amplicon analysis workflow, and it allow you to follow along with a full marker gene analysis on real microbiome data from a recent study ([Meilander _et al._ (2025)](https://doi.org/10.1093/ismeco/ycaf089)) to illustrate how you can use QIIME 2 in your own work.

There are a few exciting new features that I'd like to highlight here.

First, as the tutorial works from demultiplexed sequencing data through statistics and visualizations, it tracks a constructed data set through the analysis in 21 figures, **allowing you to visualize the data as it moves through the workflow**. That is often difficult to achieve because the data we're working with is too large to view directly, but it is hugely helpful for understanding an analysis workflow. For example, Figure 11 presents three feature tables: an original and two rarefied variants of it. If you ever find yourself wondering something like _What does this `FeatureTable[Frequency]` thing that the QIIME 2 documentation is referring to actually look like?_, this tutorial will help you understand!

 ![even-sampling-with-caption](https://forum-qiime2-org.s3.dualstack.us-west-2.amazonaws.com/original/3X/8/1/81c38b3010783e33299aeca5f7b666c7317f0f2b.jpeg)

Next, the tutorial provides 17 exercises and solutions that will guide your exploration of the data and help you test your understanding as you go. These cover topics from sequence quality control to reporting analysis reproducibility. Some of these will also push you to write new QIIME 2 commands by adapting ones that you've already seen:

 ![screenshot 2026-11-10 at 16.27.40](https://forum-qiime2-org.s3.dualstack.us-west-2.amazonaws.com/original/3X/b/5/b54010515e8f9d15e877c2346895198cc200d7fd.png)

New functionality is introduced throughout the tutorial, including [building a GTDB-based classifier using RESCRIPt](https://amplicon-docs.qiime2.org/en/stable/tutorials/gut-to-soil/#JpK7rHsmxb), [performing rarefaction-based diversity analysis with q2-boots](https://amplicon-docs.qiime2.org/en/stable/tutorials/gut-to-soil/#ds6e3w3hn8), [annotating QIIME 2 results](https://amplicon-docs.qiime2.org/en/stable/tutorials/gut-to-soil/#xMUqJ9Z5sH) (e.g., with a license or information about how to cite it when used), and [generating a QIIME 2 report which integrates multiple .qzv files into a single visualization](https://amplicon-docs.qiime2.org/en/stable/tutorials/gut-to-soil/#nQX4FhPpv6) (super convenient for publication and sharing with collaborators!).

And, when paired with the [QIIME 2 Workshop Docker Container](https://use.qiime2.org/en/stable/how-to-guides/use-the-workshop-container/), this is a great resource for running your own training events. This container provides convenient functionality built-in, including:

- a JupyterLab server that provides a consistent interface to all workshop participants (regardless of their host operating system); and
- QIIME 2 View, so your participants can double click on a `.qzv` file and have it open directly in their web browser.

When your workshop participants go home, they'll have a working installation of QIIME 2 on their computer that they can take with them to continue their learning or jump into their own data analysis.

Finally, this tutorial is currently in review for publication. In addition to [the website](https://amplicon-docs.qiime2.org/en/stable/tutorials/gut-to-soil/), if you'd like the tutorial in PDF form you can access that through the pre-print: [_Microbiome marker gene analysis with QIIME 2: the "gut-to-soil microbiome axis" tutorial_](https://zenodo.org/records/23238754). (Generally I recommend the website though as it is easier to copy/paste commands from and will be updated regularly with new versions of QIIME 2.)

Thanks to all of the co-authors on the pre-print for making this happen! If you have any feedback, please feel free to let us know.

Happy QIIMEing!

💩 → 🌱

---

<div class="post-metadata">

**Author:** ![sibilant](https://forum.qiime2.org/letter_avatar_proxy/v4/letter/s/3e96dc/32.png) [@sibilant](https://forum.qiime2.org/u/sibilant)\
**Post date:** [November 13, 2026, 10:49pm UTC](https://forum.qiime2.org/t/learn-qiime-2-with-the-all-new-gut-to-soil-tutorial/34387/2 "2026-11-13T22:49:39Z")

</div>

Congratulations to the team and thank you so much for such a valuable resource! :qiime2: 🎉

I am pretty new to Q2 but did some benchmarking of mock libraries last year with help from tutorials, including the previous version of Gut-to-Soil, before analyzing our lab's 16S and ITS data.

Firstly, I appreciate the thoughtful additional comments in the updated Gut-to-Soil tutorial related to HEC and CML! 💪 💩 🌱 The new screen-cap images are also a great addition, in my opinion.

For what it's worth, suggestions below are a few things that I personally would make use of as part of this new improved gut-to-soil tutorial, if they were added.

1. I think the tutorial primer trimming step is accessible and clear (cut by number of bases from end using qual plots). I wonder if some beginners might get the wrong impression and underestimate the importance and potential complexity of primer /adapter trimming in general, despite the caveats already stated in this section of the gut-to-soil tutorial. Maybe linking to a [q2 cutadapt tutorial](https://forum.qiime2.org/t/demultiplexing-and-trimming-adapters-from-reads-with-q2-cutadapt/2313) would help. I am grateful to the q2 forum (Soil Rotifer!) for helping me with my confusion about why it seemed like [none of the q2 tutorials trim the forward primer](https://forum.qiime2.org/t/question-about-primer-trimming-in-qiime2-16s-miseq-tutorials/34123/9). Maybe make explicit that gut-to-soil tutorial is specifically using EMP primers designed this way would help. It might also help to make explicit that it's important to always remove non-biological sequence (adapters, indices) and non-informative sequence (primers) prior to further analysis, and trimming only by qual score will not achieve this in general. Basically, raising the profile and accessibility of trimming by sequence such as with cutadapt, rather than trimming by length, might help in cases where the gut-to-soil tutorial is not just an intro to q2, but also an intro to amplicon pipelines in general.

2. I am excited to see `rachis provenance replay` continue to grow and develop! What a terrific idea and tool. I for one would love to be able to see the example `g2s-replayed.bash` file without running the tutorial, similar to how some of the other tutorial files are viewable. I haven't had a chance to use this feature yet and I'm so curious about it.

3. I have an agenda / soft spot for encouraging others to be aware of mock libraries and get all the benefits of using and analyzing them with the excellent qiime2 tools available. This is both for pedagogy, and for the [many](https://pmc.ncbi.nlm.nih.gov/articles/PMC5883066/) [benefits](https://academic.oup.com/nar/article/43/6/e37/2453415) of [including](https://www.nature.com/articles/s43705-021-00033-z) [mock library](https://link.springer.com/article/10.1186/s40793-025-00705-6) [controls](https://forum.qiime2.org/t/mock-community-assessment-and-quality-control/18776/5) as part of all experimental sequencing runs. Because Gut-to-Soil will receive a lot of well-deserved traffic, especially for beginners, maybe include a quick mention and link to the tradition of mock libraries, and the q2 tools available to analyze them? Even though I was actively looking for using q2 with mock libraries, and I'm usually pretty good at reading available software documentation, I was oblivious to these specific tools until another q2 forum member (Nicholas Bokulich!) pointed them out to me.  
Basically, maybe add a quick note to make new users aware of mock libraries, and related qiime2 actions such as `quality-control evaluate-seqs` and `evaluate-composition`, as a suggested 'next steps' for tutorial users.

4. One thing that confused me so much as a beginner was that I did not realize Qiime2 silently creates a relational database from sequences and sample info. This is despite being a user of SQL in the past. In some cases, rows and columns are switched (transformed) when data are imported into q2, which can cause a lot of confusion about how these files are meant to relate to each other, and match (pivot) on a given column for q2 to function as intended. My efforts at troubleshooting imports when I moved from the tutorial to our lab's 16S data were similarly negatively impacted by not realizing this aspect of qiime2.  
Giving folks a brief [mental model](https://forum.qiime2.org/t/feature-table-with-rep-seqs-and-samples-id/23510/2) in the Gut-to-Soil tutorial, such as about this structure below from another very helpful forum member (Colin Brislawn!) would have helped me a bunch. I think the updated tutorial does include relational info in the new screencaps and language, so I am suggesting to add a brief statement about columns transforming for some imports, and that q2 is a relational database like SQL, and maybe this useful diagram below, too.  
🔃 FeatureData[Sequence]  
feature ID  
🔃 FeatureTable[Frequency]  
sample ID  
🔃 metadata  
soil treatment groups for those samples

Congratulations again, and thank you so much for all of the care and expertise in building and sharing this fantastic tutorial! 🙏 🧡 🌱
