# Matching tools and database versions

**URL:** <https://forum.biobakery.org/t/matching-tools-and-database-versions/8505>\
**Category:** HUMAnN\
**Created:** [September 18, 2025, 9:12am UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505 "2025-09-18T09:12:49Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![mattpich](https://avatars.discourse-cdn.com/v4/letter/m/77aa72/32.png) [@mattpich](https://forum.biobakery.org/u/mattpich)\
**Post date:** [September 18, 2025, 9:12am UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/1 "2025-09-18T09:12:49Z")

</div>

Hi,

I’m new to BioBakery and I’m finding it a bit challenging to identify the correct and compatible versions of MetaPhlAn, HUMAnN, and their associated databases.

Could you share how you typically manage version compatibility? Is there a reference list or resource that outlines which versions work best together?

Thank you very much for your time and support!

Best,

Matthieu

---

<div class="post-metadata">

**Author:** ![franzosa](https://yyz1.discourse-cdn.com/flex027/user_avatar/forum.biobakery.org/franzosa/32/3511_2.png) [@franzosa](https://forum.biobakery.org/u/franzosa)\
**Post date:** [September 25, 2025, 5:19pm UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/3 "2025-09-25T17:19:46Z")

</div>

Thanks @Gsmith535 for the comments. We have been monitoring this issue and are working on a software/database version compatibility table that we will post as a pinned comment soon. We’re also working on new MetaPhlAn and HUMAnN releases that will do a better job of checking/enforcing those requirements during install and at runtime.

---

<div class="post-metadata">

**Author:** ![Gsmith535](https://avatars.discourse-cdn.com/v4/letter/g/85f322/32.png) [@Gsmith535](https://forum.biobakery.org/u/Gsmith535)\
**Post date:** [September 25, 2025, 6:02pm UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/4 "2025-09-25T18:02:57Z")

</div>

Thanks for the quick follow up, that would be super! I appreciate the effort you all are investing to develop these tools, manage databases, and document as changes occur.

---

<div class="post-metadata">

**Author:** ![mattpich](https://avatars.discourse-cdn.com/v4/letter/m/77aa72/32.png) [@mattpich](https://forum.biobakery.org/u/mattpich)\
**Post date:** [September 25, 2025, 7:15pm UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/5 "2025-09-25T19:15:50Z")

</div>

Thanks a lot for your help.

---

<div class="post-metadata">

**Author:** ![mattpich](https://avatars.discourse-cdn.com/v4/letter/m/77aa72/32.png) [@mattpich](https://forum.biobakery.org/u/mattpich)\
**Post date:** [September 25, 2025, 7:16pm UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/6 "2025-09-25T19:16:15Z")

</div>

Looking forward to thos software/database.  
Thanks Eric

---

<div class="post-metadata">

**Author:** ![mattpich](https://avatars.discourse-cdn.com/v4/letter/m/77aa72/32.png) [@mattpich](https://forum.biobakery.org/u/mattpich)\
**Post date:** [April 7, 2026, 6:57pm UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/7 "2026-04-07T18:57:58Z")

</div>

Hi Eric,  
Any update on the software/database version compatibility table?  
Many thanks for your time considering this request.

---

<div class="post-metadata">

**Author:** ![nickp60](https://yyz1.discourse-cdn.com/flex027/user_avatar/forum.biobakery.org/nickp60/32/1031_2.png) [@nickp60](https://forum.biobakery.org/u/nickp60)\
**Post date:** [April 9, 2026, 3:04pm UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/8 "2026-04-09T15:04:22Z")

</div>

You can get a rough table as follows:

```auto
  for tag in 3.1.1 3.5 3.6.1 3.7 v3.8 v3.9 4.0.0.alpha.1 4.0.0.alpha.1-final ; do git checkout $tag ; cat humann/config.py | grep -e "metaphlan_v4_db_version\|metaphlan_v4_db_matching_uniref\|matching_uniref" | sed "s|^|$tag\t|g" ; done > version_table
cat version_table

3.1.1 metaphlan_db_matching_uniref="v201901_v31"
3.1.1 matching_uniref="201901b"
3.5 metaphlan_v4_db_version="vJan21"
3.5 metaphlan_v3_db_matching_uniref="v201901_v31"
3.5 matching_uniref="201901b"
3.6.1 metaphlan_v4_db_version="vJan21"
3.6.1 metaphlan_v3_db_matching_uniref="v201901_v31"
3.6.1 matching_uniref="201901b"
3.7 metaphlan_v4_db_version="vOct22"
3.7 metaphlan_v3_db_matching_uniref="v201901_v31"
3.7 matching_uniref="201901b"
v3.8 metaphlan_v4_db_version="vOct22"
v3.8 metaphlan_v3_db_matching_uniref="v201901_v31"
v3.8 matching_uniref="201901b"
v3.9 metaphlan_v4_db_version="vJun23"
v3.9 metaphlan_v3_db_matching_uniref="v201901_v31"
v3.9 matching_uniref="201901b"
4.0.0.alpha.1 metaphlan_v4_db_version="vOct22"
4.0.0.alpha.1 metaphlan_v4_db_matching_uniref="SGB"
4.0.0.alpha.1 matching_uniref="2019_06"
4.0.0.alpha.1-final metaphlan_v4_db_version="vOct22_CHOCOPhlAnSGB_202403"
4.0.0.alpha.1-final metaphlan_v4_db_matching_uniref="SGB"
4.0.0.alpha.1-final matching_uniref="2019_06"

```

---

<div class="post-metadata">

**Author:** ![mattpich](https://avatars.discourse-cdn.com/v4/letter/m/77aa72/32.png) [@mattpich](https://forum.biobakery.org/u/mattpich)\
**Post date:** [April 9, 2026, 3:36pm UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/9 "2026-04-09T15:36:33Z")

</div>

Thank you @nickp60 it certainly helps.

What would further help is a consolidated list or matrix documenting the compatibility between HUMAnN software and database versions and MetaPhlAn software and database versions, covering both the officially paired versions and any validated backward‑compatible configurations.  
This would help determine when MetaPhlAn results need to be reprocessed prior to running HUMAnN.

---

<div class="post-metadata">

**Author:** ![nickp60](https://yyz1.discourse-cdn.com/flex027/user_avatar/forum.biobakery.org/nickp60/32/1031_2.png) [@nickp60](https://forum.biobakery.org/u/nickp60)\
**Post date:** [April 9, 2026, 4:04pm UTC](https://forum.biobakery.org/t/matching-tools-and-database-versions/8505/10 "2026-04-09T16:04:33Z")

</div>

100% agree. We moved to just supporting a handful of version sets and built [containers](https://github.com/vdblab/dockerfiles/pkgs/container/biobakery-profiler) for the working combos. Some notes about them [here.](https://github.com/vdblab/dockerfiles/blob/main/biobakery_README.md)
