Troubleshooting humann in 2026 CE

Microbial community profiling HUMAnN
1

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.


/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.