MetaPhlAn 4 + HUMAnN 4 compatibility

Microbial community profiling HUMAnN
1

HUMAnN users - I’m making a quick pinned post about MetaPhlAn 4 + HUMAnN 4 compatibility since we’re seeing a lot of posts raising similar issues. We will follow up with more detailed information in the short term, and longer-term we’re also improving our version checking at install and runtime to avoid some of these issues going forward.

Key point 1: The current HUMAnN 4 release (v4.0.0.alpha.1) should work with MetaPhlAn 4 releases up to v4.1.1. It does not support v4.2+, which introduced an API change we still need to adapt to.

Key point 2: All versions of HUMAnN work with specific MetaPhlAn marker databases, since we require compatibility between MetaPhlAn’s markers + taxonomy and HUMAnN’s pangenomes + functional annotations. To use HUMAnN 4.0.0.alpha.1, you should be working with the mpa_vOct22_CHOCOPhlAnSGB_202403 MetaPhlAn marker database. If you install (or update to) a newer marker database it will break HUMAnN 4 compatibility.

If you’re working with older versions of HUMAnN (e.g. v3.9) in MetaPhlAn 4 compatibility mode, please see the release notes for your specific version of HUMAnN for the correct MetaPhlAn software and marker versions.

Apologies to those that have been struggling with HUMAnN installation as a result of the constraints above, and thanks for raising awareness here.

4 Likes
3

Hello,

I followed the instructions (HERE) to download and install Humann4 + Metaphlan4 database, and I am getting the following ERROR:

ERROR: The MetaPhlAn taxonomic profile provided does not contain the database version vOct22_CHOCOPhlAnSGB_202403 in any of its header lines.

I downloaded the Metaphlan database using: metaphlan --install --index mpa_vOct22_CHOCOPhlAnSGB_202403

Checking the download output, I noticed I got files from mpa_vOct22_CHOCOPhlAnSGB_202403 and mpa_vJan25_CHOCOPhlAnSGB_202503 versions. See them below:

mpa_latest; mpa_vJan25_CHOCOPhlAnSGB_202503.pkl mpa_vOct22_CHOCOPhlAnSGB_202403.2.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.rev.2.bt2l
mpa_vJan25_CHOCOPhlAnSGB_202503.1.bt2l mpa_vJan25_CHOCOPhlAnSGB_202503.rev.1.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.3.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403_VINFO.csv
mpa_vJan25_CHOCOPhlAnSGB_202503.2.bt2l mpa_vJan25_CHOCOPhlAnSGB_202503.rev.2.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.4.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403_VSG.fna
mpa_vJan25_CHOCOPhlAnSGB_202503.3.bt2l mpa_vJan25_CHOCOPhlAnSGB_202503_VINFO.csv mpa_vOct22_CHOCOPhlAnSGB_202403.pkl README.txt
mpa_vJan25_CHOCOPhlAnSGB_202503.4.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.1.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.rev.1.bt2l

Any advice?

Thanks

4

It’s because “metaphlan” is using the "latest” version of the database: I worked around the problem by changing the “latest” version file:

cd .conda/envs/humann/lib/python3.12/site-packages/metaphlan/metaphlan_databases
mv -i mpa_latest mpa_latest.dist
echo mpa_vOct22_CHOCOPhlAnSGB_202403 > mpa_latest

5

Hello, fellow bioBakers! :waving_hand:

Apologies if this isn’t the right thread for my question — please let me know if I should post it separately.

I’ve recently started working on metatranscriptomics with a focus on the gut microbiota, and I’m currently running HUMAnN v4.0.0.alpha.1 with MetaPhlAn v4.1.1 (11 Mar 2024).

However, I’ve noticed something odd: in my utility_mapping subdirectory, I have the files mpa_vJan21_CHOCOPhlAnSGB_202103.tsv and vOct22_SGB_mapping.tsv, even though my MetaPhlAn database is mpa_vOct22_CHOCOPhlAnSGB_202403.

Did I miss a step during installation or database setup?

Should I manually download the corresponding mpa_vOct22_CHOCOPhlAnSGB_202403.tsv file from somewhere else?

Any guidance or clarification would be greatly appreciated!

Best,
Fran :man_technologist:

6

Same with a fresh installation here:
mpa_vJan21_CHOCOPhlAnSGB_202103.tsv and vOct22_SGB_mapping.tsv.

Is it really compatible with MetaPhlAn v4.1.1 + mpa_vOct22_CHOCOPhlAnSGB_202403?

When installing HUMAnN following the details here, MetaPhlAn v4.2.4 is installed.

humann --version
humann v4.0.0.alpha.1

metaphlan --version
MetaPhlAn version 4.2.4 (21 Oct 2025)

Some clarification would be super helpful !

1 Like
7

Hello Biobakers,

I am wondering if you have some updates on this?

Many thanks!

8

I struggled with similar issues described here when trying to get humann4 v4.0.0.alpha.1 running in my compute environment. I eventually got it working and these were the key things that helped me:

  1. setup conda channels
    conda config --add channels defaults
    conda config --add channels conda-forge
    conda config --add channels bioconda
    conda config --add channels biobakery

  2. specify versions when installing via conda
    conda create -n humann4 python=3.12
    conda activate humann4
    conda install humann=4.0.0a1
    conda install metaphlan=4.1.1

  3. Download the correct database versions to specific paths
    metaphlan --install --db_dir metaphlan_databases/vOct22 --index mpa_vOct22_CHOCOPhlAnSGB_202403
    humann_databases --download uniref uniref90_ec_filtered_diamond humann4_dbs/
    humann_databases --download chocophlan full humann4_dbs/
    humann_databases --download utility_mapping full humann4_dbs/

  4. Specify database paths for both humann and metaphlan in the command
    humann -r -i SAMPLE.fq.gz -o ./SAMPLE/ --threads 16 --protein-database humann4_dbs/uniref --nucleotide-database humann4_dbs/chocophlan --metaphlan-options "-t rel_ab_w_read_stats --bowtie2db metaphlan_databases/vOct22 --index mpa_vOct22_CHOCOPhlAnSGB_202403"

  5. For me it was critical to include -t rel_ab_w_read_stats in the --metaphlan-optionsstring, otherwise metaphlan reverted to the default -t value which causes humann4 to not recognize it as a valid taxonomic profile

Hopefully this will all be outdated when a non-alpha release of Humann4 drops soon!

2 Likes
9

Thanks a lot! This works for me as well!

10

Hi @klomp030! :waving_hand:

Did you manage to get the corresponding mpa_vOct22_CHOCOPhlAnSGB_202403.tsv in your utility_mapping subdirectory?

I would appreciate any guidance or clarification on this front.

Best,
Fran :man_technologist:

1 Like
11

Thanks for sharing your setup steps, @jtrachsel! :+1:

I wanted to add a note about step 3: the MetaPhlAn database installation. In my environment, the command you suggested:

metaphlan --install --db_dir metaphlan_databases/vOct22 --index mpa_vOct22_CHOCOPhlAnSGB_202403

didn’t work as expected. Instead, I had to use --bowtie2db instead of --db_dir:

metaphlan --install --bowtie2db data/databases/metaphlan/vOct22_CHOCOPhlAnSGB_202403 --index mpa_vOct22_CHOCOPhlAnSGB_202403

This might be version-specific behavior or environment-dependent, but I thought it worth mentioning for others who might encounter the same issue.

Also, the root issue I was originally referring to relates to the utility_mapping database: the file mpa_vOct22_CHOCOPhlAnSGB_202403.tsv appears to be missing from the full_mapping_v4_alpha.tar.gz archive. I’ve opened a separate thread to discuss this issue in detail, as it affects compatibility with MetaPhlAn v4.1.1 and the mpa_vOct22_CHOCOPhlAnSGB_202403 database.

Thanks again for documenting your working setup; it’s been very helpful!

Best,
Fran
:man_technologist: