# Troubleshooting humann in 2026 CE **URL:** \ **Category:** HUMAnN\ **Created:** [October 1, 2026, 12:19pm UTC](https://forum.biobakery.org/t/troubleshooting-humann-in-2026-ce/9074 "2026-10-01T12:19:29Z")\ **Posts on this page:** 3\ **Page:** 1
**Author:** ![handibles](https://yyz1.discourse-cdn.com/flex027/user_avatar/forum.biobakery.org/handibles/32/1191_2.png) [@handibles](https://forum.biobakery.org/u/handibles)\ **Post date:** [October 1, 2026, 12:19pm UTC](https://forum.biobakery.org/t/troubleshooting-humann-in-2026-ce/9074/1 "2026-10-01T12:19:29Z")
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` ```auto 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` ```auto 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: ```auto humann -i $h4/demo.fastq -o $h4/demo_results ``` ## Different Errors: ```auto 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)](https://github.com/biobakery/humann/commit/4404f2af92c0d0a01df171534c508f94c137d6b2). 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 ```auto 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. ```auto 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 ```auto 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. ```auto 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](https://forum.biobakery.org/t/humann4-not-recognizing-relab-column-in-metaphlan4-table/8647) )) - 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](https://docs.google.com/document/d/1rCx5JkuO7wCKWrL8%5C_-UJx_FkopJAfcDFtZktgPspak0/edit?tab=t.0) ]. If databases change, you’ll need to update this also. ```auto /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\d+)', aline) Error when running glpsol from MinPath. ``` - known issue with changes in `Py3.12` ([see [u]here[/u]](https://forum.biobakery.org/t/humann-4-0-0a1-minpath12hmp-py-syntaxwarning/8606)), despite instructions in the `H4 4.0.0a1` docs to pin `python=3.12.` To be updated as encountered. ---
**Author:** ![handibles](https://yyz1.discourse-cdn.com/flex027/user_avatar/forum.biobakery.org/handibles/32/1191_2.png) [@handibles](https://forum.biobakery.org/u/handibles)\ **Post date:** [October 5, 2026, 2:17pm UTC](https://forum.biobakery.org/t/troubleshooting-humann-in-2026-ce/9074/2 "2026-10-05T14:17:01Z")
## one more problem ```auto 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\<](https://github.com/biobakery/humann#faqs) 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\<](https://forum.biobakery.org/t/humann-4-0-0a1-minpath12hmp-py-syntaxwarning/8606/2), 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. ---
**Author:** ![handibles](https://yyz1.discourse-cdn.com/flex027/user_avatar/forum.biobakery.org/handibles/32/1191_2.png) [@handibles](https://forum.biobakery.org/u/handibles)\ **Post date:** [October 5, 2026, 2:25pm UTC](https://forum.biobakery.org/t/troubleshooting-humann-in-2026-ce/9074/3 "2026-10-05T14:25:12Z")
## working install installed early Oct '26. ```auto 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: ```auto 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\<](https://forum.biobakery.org/t/humann-4-0-0a1-minpath12hmp-py-syntaxwarning/8606/2) Happy hunting!