📚 课程目录第2章 MetaPhlAn安装与版本选择

2. MetaPhlAn 安装与版本选择

MetaPhlAn 的安装看起来简单，但选错了方式或版本，后面跑起来全是坑。我个人见过太多人卡在依赖冲突上，所以我习惯把安装分成三种场景来说。

2.1 Conda 安装：最简单，也最稳

如果你问我推荐哪种方式，我肯定首选 Conda。尤其是跑生物信息工具，Conda 能自动处理 Python 版本、依赖包、甚至 C/C++ 库的冲突。我当年第一次装 MetaPhlAn 时，图省事用 pip，结果 Build 报告一跑就崩，换成 Conda 后一次性过。

具体命令也很简单：

conda create -n metaphlan_env python=3.8
conda activate metaphlan_env
conda install -c bioconda metaphlan

装完之后，你最好加一个测试：

metaphlan --version

如果能输出版本号，说明核心包已经就绪。不过别高兴太早，数据库还得单独下载：

metaphlan --install  # 会自动下载 bowtie2 索引和 marker 数据库

小技巧：我习惯先看看 conda 源是不是设了 bioconda 频道。如果遇到下载慢，可以加 -c conda-forge，或者换成国内镜像——比如清华 tsinghua。具体改法：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/bioconda

2.2 Pip 安装：轻量但需要你清楚依赖

Pip 安装快，包体小，适合已经有干净 Python 环境的老手。但我必须提醒：MetaPhlAn 依赖 Bowtie2（C++ 程序），而 pip 管不了非 Python 的包。你得自己提前装好 Bowtie2。

pip install metaphlan

如果缺了 bowtie2，运行时就会报错：

Error: bowtie2 not found in PATH

碰到这情况，用 Conda 装一个 bowtie2 就行，或者从源码编译：

conda install -c bioconda bowtie2

另一个坑：pip 安装时可能会自动升级 numpy、pandas 等库，如果你项目里还有其他工具在用旧版，很容易冲突。我建议先在虚拟环境里装：

python3 -m venv metaphlan_venv
source metaphlan_venv/bin/activate
pip install metaphlan

警告：Python 3.11 及以上版本暂不完全兼容 MetaPhlAn 4.x。我实测过 3.11 装 4.0.6 报错，换成 3.9 就没事。所以建议你用到 3.8 或 3.9。

2.3 源码编译：定制党专属

源码安装适合想修改代码、或者需要极端性能优化的朋友。MetaPhlAn 本身是纯 Python 项目，但数据库和 bowtie2 索引需要额外处理。

步骤：

git clone https://github.com/biobakery/MetaPhlAn.git
cd MetaPhlAn
python setup.py install

不过很多人在 setup.py 阶段会遇到依赖解析失败。我建议你先用 Conda 建一个干净环境，再 pip install -e . 从源码链接安装：

conda create -n metaphlan_dev python=3.8
conda activate metaphlan_dev
git clone https://github.com/biobakery/MetaPhlAn.git
cd MetaPhlAn
pip install -e .

这样改完代码直接生效，不用重复安装。

2.4 版本选择：别追新，要追稳

MetaPhlAn 目前活跃分支是 4.x，比 3.x 快很多（这个课程后面会细讲优化）。但版本号里暗藏玄机。

版本	Python 兼容	数据库大小	适用场景
MetaPhlAn 3.0	3.6-3.9	~2.5 GB	旧项目兼容、低内存环境
MetaPhlAn 4.0.3	3.7-3.10	~2.8 GB	推荐生产环境，稳定
MetaPhlAn 4.1+	3.8-3.11	~3.1 GB	需要最新 marker 库时选用

我个人建议：新项目直接上 4.0.3，如果要处理极低丰度的物种检测，可以试试 4.1+。但别盲目装 latest——我踩过一次坑，装完 4.1.0 后数据库索引格式变了，旧有的 bowtie2 索引全得重新下，浪费半天。

版本匹配口诀：

Python 3.8/3.9 + MetaPhlAn 4.0.3 = 黄金组合
Python 3.10/3.11 + MetaPhlAn 4.1+ = 新功能尝鲜
Python 3.6/3.7 -> 只能用 MetaPhlAn 3.x（但数据库更新已经停了）

2.5 根据系统选择合适版本

MetaPhlAn 主要在 Linux 下开发，跑得也最快。你想想看，bowtie2 在 Linux 上用 AVX2 指令集加速，比对速度能快 30%。

Linux (Ubuntu 20.04+ / CentOS 7+)：全功能支持，推荐 Conda 安装。注意 glibc 版本要 ≥2.17。
macOS (Intel / Apple Silicon)：Intel 的没问题。M1/M2 芯片需要 Rosetta 2 转译 bowtie2，最好用 Conda 装原生 arm64 构建的 bowtie2。
Windows：官方不支持原生安装。我试过用 WSL2 + Ubuntu 22.04，所有功能正常。别在原生 Windows cmd 上折腾，浪费时间。

检查 bowtie2 是否支持你的 CPU：

bowtie2 --version | grep "bowtie2-align-s"

如果输出包含 POPCNT、SSE4.2，说明硬件加速已启用。没有的话也别慌，只是慢一点。

2.6 避坑指南：我遇到过的三个常见问题

问题 1：版本冲突，安装报红
场景：conda 创建多个环境后，装 MetaPhlAn 时卡在 solving environment 数小时。

解决：先用 conda clean --all 清理缓存，再新建环境指定依赖：

conda create -n mp4 python=3.8 metaphlan=4.0.3 bowtie2

问题 2：数据库下载失败
场景：metaphlan --install 卡在 90%，或者报 403 错误。

解决：手动下载数据库压缩包，放到 ~/.metaphlan_databases/ 下：

wget https://huttenhower.sph.harvard.edu/metaphlan_data/mpa_vJan21_CHOCOPhlAnSGB_202103.tar.bz2
tar -xjf mpa_vJan21_CHOCOPhlAnSGB_202103.tar.bz2 -C ~/.metaphlan_databases/

问题 3：bowtie2 索引不兼容
场景：你装的是 MetaPhlAn 4.x，但数据库还是 3.x 的索引。

解决：检查 metaphlan --version 和 ls ~/.metaphlan_databases/。如果文件名不匹配，重新运行 metaphlan --install --bowtie2db /path 指定路径。

对了，还想起一个事：如果你同时用 MetaPhlAn 和 Kraken2，两个工具会竞争 bowtie2 的版本。最好分开建 Conda 环境，互不干扰。

2.7 安装后验证清单

装完之后，花 1 分钟跑个快速验证：

metaphlan --version
bowtie2 --version
metaphlan --help | head -10

然后拿单端测试数据跑一下：

metaphlan /path/to/test.fastq --input_type fastq --bowtie2db ~/.metaphlan_databases/ --nproc 2 --output_file test_metagenome.txt

如果这一步没报错，恭喜你，安装成功了。接下来的章节，我会带你把这些命令跑出更好的性能——内存大小、线程数、数据库路径，每一个都可能让速度翻倍。