Troubleshooting humann in 2026 CE

[handibles]

Reference / cheatsheet / ill manifesto of installing and debugging HUMAnN 4.0.0a1 & co. Possibly issues stemmed from not following the signposts properly - possibly from byzantine documentation and a copse of incompatibilities between MP and H.

working install - HUMAnN3

As of September 2026, pip builds HUMAnN3 (but not HUMAnN4).

Cooperating versions: H3.9; MP3.1.0; Python 3.11; Bowtie2 2.5.5 (but x86-64-v3 fails and falls back D6" to default); Diamond 2.0.15 ; MinPath 1.6

h3=/path/to/workspace/for/humann3
h3ref=/path/to/databases/for/humann3            

mamba create -n h3pip python=3.12 -y ; mamba activate h3pip

# forgot the --no-binary flag and installed bt2, D, and minpath via maba
pip install humann --no-binary :all:
humann --version

# get db and update config if/as necessary
humann_databases --download chocophlan full $h3ref &
humann_databases --download uniref uniref90_diamond $h3ref
humann_config 
humann_config --update database_folders nucleotide $h3ref/chocophlan
humann_config --update database_folders protein $h3ref/uniref

# need this too
pip install metaphlan==3.1.0
metaphlan --version

humann --input $h4/demo.fastq --output $h4/demo_pip

working install - HUMAnN4

Note: set python=3.11, and *not* python=3.12 as instructed in the documentation - avoids clash with MinPath below.

possibly cooperating versions: MinPath v1.6 ; Bowtie2 v2.5.5 (Failed to launch x86-64-v3 version, staying with default Failed to launch x86-64-v3 version, staying with default) ; Diamond v2.0.15 ; MP v4.1.1 ; H v4.0.0.alpha.1

h4=/path/to/workspace/for/humann4
h4ref=/path/to/databases/for/humann4            

mamba create --name h4 python=3.11 -y ; mamba activate h4

conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
conda config --add channels biobakery

mamba install humann=4.0.0a1 -c biobakery -y

humann_databases --download chocophlan full $h4ref &
humann_databases --download uniref uniref90_ec_filtered_diamond $h4ref &
humann_databases --download utility_mapping full $h4ref

# mp seemingly installed alongside humann
# note - see also error below where H & MP databases must be same version 
metaphlan --install --bowtie2db $h4ref/metaphlan_databases --index mpa_vOct22_CHOCOPhlAnSGB_202403
            
humann -i $h4/demo.fastq -o $h4/demo_results --threads 40 --metaphlan-options="--bowtie2db  $h4ref/metaphlan_databases"

The rails begin to buckle somewhat when we try the following - troubleshooting below:

humann -i $h4/demo.fastq -o $h4/demo_results

Different Errors:

CRITICAL ERROR: Can not call software version for metaphlan

• if installed by mamba/conda, metaphlan is present and working - this is just a mis-parse between H & MP versions, where metaphlan --version now gives a two lines of output, creating issue already addressed in the lovely PR that’s still open from @nearinj at github (link). Manually patched in local install by opening humann.config via nano $( python -c "import humann.config as c; print(c.file)" ) and editing "line" : -1 to "line" : 0 for metaphlan_version, circa line #373.
• note this seems to be a current critical bug

error: [Errno 17] File exists: '/home/user/bin/miniforge3/envs/h4p/bin/python3.12'

• this from starting a fresh conda env with pinned python=3.12 when running python setup.py install --user. Didn’t solve, simply ran away and tried something else.

Error: WARNING: Can not call software version for bowtie2

• bowtie2 --version gives: [WARNING] Failed to launch x86-64-v3 version, staying with default. Not a critical issue, a warning only - hopefully H4 will still run

metaphlan: error: unrecognized arguments: --bowtie2out /path/.../demo_humann_temp/demo_metaphlan_bowtie2.txt

• The output folder H4 checks was renamed from MP 4.2 onwards - get the correct version via mamba install biobakery::metaphlan=4.1 -y as outlined above.

ERROR: The relative abundance and coverage were not found in the MetaPhlAn taxonomic profile. Please run MetaPhlAn with the option(s): --bowtie2db /workspace/user/db/humann4/metaphlan_databases.

• This is a missed step from setup - need matching H4 and MP4 database versions as mentioned above (and [here]( Humann4 not recognizing relab column in metaphlan4 table ))
• resolve with metaphlan --install --bowtie2db $h4ref/metaphlan_databases --index mpa_vOct22_CHOCOPhlAnSGB_202403 to match the H4 Oct22 database, as currently noted in the H.4.0.0a1 notes [ https://docs.google.com/document/d/1rCx5JkuO7wCKWrL8\_-UJx_FkopJAfcDFtZktgPspak0/edit?tab=t.0 ]. If databases change, you’ll need to update this also.

/home/user/bin/miniforge3/envs/h4pip/lib/python3.12/site-packages/humann/quantify/MinPath12hmp.py:804: SyntaxWarning: invalid escape sequence '\d'
  m = re.match('^[^\d]+(?P<id>\d+)', aline)
Error when running glpsol from MinPath.

• known issue with changes in Py3.12 (see [u]here[/u]), despite instructions in the H4 4.0.0a1 docs to pin python=3.12.

To be updated as encountered.

[handibles]

one more problem

ERROR: The relative abundance and coverage were not found in the MetaPhlAn taxonomic profile. Please run MetaPhlAn with the option(s): --index mpa_vOct22_CHOCOPhlAnSGB_202403.

• Note: error message mentions rel_ab and coverage as missing - default -t arg is rel_ab only
• solution - specify --metaphlan-option="-t rel_ab_w_read_stats"
• this worked when all of the following had already been checked and unsuccessful:
  • compared MP4 and H4 demo_1_metaphlan_profile.tsv output headers - both were correct match (vOct22)
  • deleted and reinstalled databases
  • checked format for --metaphlan-options - note both seem to work fine:
    • --metaphlan-options="-t rel_ab_w_stats" # separated by space
    • --metaphlan-options "-t rel_ab_w_stats" # separated by =
    • see also >here< and humann.py line# 1332
    • everything else above also. Note using Py3.12 in this env - this is a problem for MinPath as noted >here<, dealt with below.

Seems mad that this one weird trick is required, but possibly issue arises from M/H versions not quite matching via a combination not encountered elsewhere.

[handibles]

working install

installed early Oct '26.

h4ref=/path/to/db/folder
h4=/path/to/humann4_work/with_demo_fastq_file

## min hacks for min paths  -  mamba+pip, what could go wrong
mamba create -n h4p311 python=3.11 -y ; mamba activate h4p311
conda config --add channels defaults 
conda config --add channels bioconda 
conda config --add channels conda-forge 
conda config --add channels biobakery 

# note custom versions for MP4, BT2, D
pip install humann==4.0.0a1 --no-binary :all:
mamba install metaphlan=4.1.1 -y
mamba install bowtie2=2.5.4 -y
# Minpath 1.12 builtin , stays as it it.

# run & then get lunch
humann_databases --download chocophlan full $h4ref --update-config yes &
humann_databases --download uniref uniref90_ec_filtered_diamond $h4ref --update-config yes &
humann_databases --download utility_mapping full $h4ref --update-config yes &
metaphlan --install --index mpa_vOct22_CHOCOPhlAnSGB_202403

humann --input $h4/demo.fastq --output $h4/demo_mamb --threads 40 --metaphlan-options "-t rel_ab_w_read_stats"

Gives fully sane output. Final sanity - version checks:

head -20 ~/bin/MinPath/MinPath.py ; bowtie2 --version ; diamond --version ; metaphlan --version ; humann --version

# dross removed 
# >  MinPath built into H4, v. 1.12
# >  /home/user/bin/miniforge3/envs/h4u/bin/bowtie2-align-s version 2.5.4
# >  diamond version 2.0.15
# >  MetaPhlAn version 4.1.1 (11 Mar 2024)
# >  humann v4.0.0.alpha.1

• CRITICAL ERROR: Can not call software version for metaphlan was ~solved by specifying MP4.1.1 when creating/installing the env. As mentioned above, it can also be patched by setting "line" : 0 for metaphlan_version, circa line #373 of humann_config after installation.

• miniforge3/envs/h4u/lib/python3.12/site-packages/humann/quantify/MinPath12hmp.py:804: SyntaxWarning: invalid escape sequence '\\d' addressed by setting python=3.11 as >recommended here<
  
  
  Happy hunting!