BRAKER2安装全攻略：从依赖配置到成功运行

1. 先说清楚：BRAKER2是干什么的，为什么安装是道坎

1.1 一段话讲明白BRAKER2的定位

如果你手里有一个组装好的真核基因组，比如真菌、植物或者昆虫，下一步最想做的多半就是基因结构预测——也就是把基因组上的基因位置、外显子、内含子、CDS边界、蛋白序列这些信息注释出来。手动一个个看太不现实，RNA-seq比对信号加同源蛋白比对信息一套，交给自动注释软件去整合，是当前团队最常用的做法。BRAKER2就是这个环节里非常关键的一条自动化流水线。

BRAKER2的核心能力是：在一条命令里完成GeneMark家族（GeneMark-ES/ET/ETP）和Augustus两套工具的串联。它先用RNA-seq比对产生的BAM文件或者蛋白库来训练从头预测工具，然后再用训练好的参数去预测基因结构，最后把结果统一输出成GFF3、蛋白序列、CDS序列等文件。相比手动分别跑GeneMark、Augustus再手工合并，BRAKER2省掉的不仅是命令行次数，更是中间大量容易出错的格式转换和坐标转换工作。

我第一次接触BRAKER2是在一个大约40Mb的真菌基因组项目上，当时已经用MAKER跑过一轮，光是准备训练集和调整repeat library就花了一周。换成BRAKER2之后，直接用已有的hisat2比对BAM文件，--softmasking --gff3两个参数，整套预测流程一天之内跑完，输出结果直接进入下游功能注释流程。从那以后，BRAKER2就成了我的默认工具之一。

1.2 依赖链特别长，安装难点从哪来

BRAKER2本身其实是一堆Perl脚本，真正的工作全部依赖底层的第三方工具。粗略列一下主要依赖：

• Augustus（核心基因预测器，训练和预测都靠它）
• GeneMark-ES / ET / ETP（从头预测模块）
• bamtools（处理BAM文件的库和命令行工具）
• samtools、bedtools（BAM排序、格式处理）
• hisat2或STAR（RNA-seq比对，不过如果你只给BAM文件，这部分只需要比对结果）
• diamond（蛋白序列快速比对，用于--prot_seq模式）
• spaln（蛋白直系同源外显子比对，同源注释会用到）
• Python2环境（BRAKER2部分脚本仍在Python2上运行，这一步在较新系统上尤其容易出问题）

从这个清单你就能看出来，安装BRAKER2本质上是在给一台机器配齐一整套生物信息学基础环境。难点不只在于"下载安装每个软件"，还在于版本之间的兼容性、路径顺序、编译选项、许可文件位置，任何一个环节出错，最后跑braker.pl的时候都会以各种报错来考验你。

所以，这篇文章接下来我不会只给你"复制粘贴几条命令"，而是会把两种安装路线、环境配置、测试验证、常见报错都走一遍，按我个人反复折腾之后觉得最顺的顺序来写。

2. 路线选型：conda装还是源码装，利弊一次说完

2.1 conda安装：三四条命令确实省事，但也有隐藏限制

如果你平时已经在用conda环境管理生信软件，那装上BRAKER2最直接的方案就一条命令：

conda create -n braker2 -c conda-forge -c bioconda braker2=2.1.6

注意频道顺序，conda-forge放前面，bioconda放后面，两边冲突时以conda-forge的版本解析为准，这是社区里反复验证过的顺序。装完之后进入环境：

conda activate braker2 which braker.pl

能看到braker.pl路径，说明主程序已经就位。

cnda 方案最大的好处是依赖项基本由conda自动解析，包括bamtools、samtools、hisat2、diamond这些都会在环境里一起装好，不需要你手工指定路径。对于只想快速跑通流程的人来说，这是成本最低的路线。

但你必须知道它的隐藏限制：GeneMark的许可组件不会通过conda自动配好。GeneMark-ES/ET系列的工具虽然会随包安装二进制文件，但运行时需要用到的许可文件.gm_key仍然要你自己去官方申请。此外，conda源的GeneMark版本可能不是最新，某些晚期功能（比如ETP模式相关的新版本工具名）可能缺失。

还有一点，conda装的Augustus会把config目录放在conda环境内，路径比较深。如果你在集群或共享机器上跑，注意AUGUSTUS_CONFIG_PATH要指向环境内的config目录，并且具备写权限，否则训练过程中去写物种参数时会直接报错。

2.2 源码安装：完全可控，但准备工作要做好

如果你打算长期做注释项目，或者需要在集群上复现一套严格可控的环境，建议走源码安装。这个方案花的时间多，但你能精确知道每个工具装在哪个目录、什么版本，出了问题也能自己排查。

我推荐的依赖安排分三层：

• 系统包层：build-essential、git、cmake、wget、libgsl-dev，用系统包管理器装好
• 核心工具层：Augustus、GeneMark、bamtools、samtools、bedtools、hisat2、diamond、spaln，全部源码编译
• 主程序层：BRAKER2源码，只需要把scripts目录加入PATH

不需要unzip额外系统依赖，BRAKER2的perl模块本身在源码包里都带好了，只需要把路径导出到PERL5LIB。下面第3节我会把这套流程一步一步拆开。

为了帮你快速判断选哪条路，我给一张对比表：

对比项	conda安装	源码安装
安装耗时	十分钟内	半天到一天
依赖解析	自动处理	需手动逐个解决
GeneMark许可	仍需要手动配置	仍需要手动配置
版本控制	依赖bioconda收录情况	完全自主
排错难度	报错信息偏间接	可直接定位编译和路径问题
适用场景	快速跑通、个人环境	生产环境、集群复现

我的建议是：第一次接触就装，优先conda，先把BRAKER2跑通，理解它的输入输出之后，如果确定要大量使用，再花时间整理一套源码编译环境。

3. 核心装载步骤：从依赖到主程序，我这样装成功

下面这套流程以Ubuntu 20.04为例，假设用户目录是/home/user，所有工具集中放在/home/user/biosoft下。

3.1 Augustus与周边工具的编译细节

先创建目录并下载Augustus：

mkdir -p ~/biosoft && cd ~/biosoft git clone https://github.com/Gaius-Augustus/Augustus.git cd Augustus

Augustus的编译，直接make大概率能过，但有两个编译选项建议提前确认：ZIPINPUT（是否需要支持压缩的输入文件）和COMPGENEPRED（是否编译另一套预测器），一般在Makefile文件里以注释行存在。如果不需要额外功能，默认编译就行。编译结束后，重点检查几个文件：

• bin/etraining
• bin/augustus
• bin/autoAug.pl
• config/species/下面有没有样例物种目录

接下来把Augustus相关路径配好，这一步在后面第4节会展开，但此时先记住：config目录在~/biosoft/Augustus/config，后面BRAKER2必须能写这个目录。

然后编译bamtools。bamtools官方推荐用cmake构建：

cd ~/biosoft git clone https://github.com/pezmaster31/bamtools.git cd bamtools mkdir build && cd build cmake .. make sudo make install

注意，安装完之后bamtools的库文件可能被放在/usr/local/lib/bamtools/，而头文件在/usr/local/include/bamtools/。如果你不在/usr/local下安装，就记住自己的安装路径，后面配置LD_LIBRARY_PATH和CMAKE_PREFIX_PATH时会用上。

samtools和bedtools相对简单，Ubuntu下可以直接用apt装，也可以源码编译。我个人习惯源码编译samtools，因为它更新频繁，版本之间行为差异大。bedtools用apt装通常就够跑了。

3.2 GeneMark系列：许可证是绕不过去的一环

GeneMark-ES/ET/ETP是BRAKER2的组成部分，需要单独获取。官方下载流程是这样的：到GeneMark官网的下载页面填写申请，用机构邮箱注册，通常几个小时内会收到一封带下载链接的邮件，里面包含Linux 64位的GeneMark-ES/ET工具包和一份许可证说明。

下载后把包解开，放到~/biosoft/gmes_linux下，并确认关键脚本存在：

ls ~/biosoft/gmes_linux/gmes_petap.pl

接下来是全网装BRAKER2时最容易翻车的点：许可证文件必须叫.gm_key，放在用户主目录下。把邮件里收到的key文件内容保存到$HOME/.gm_key，然后修改权限：

chmod 600 ~/.gm_key

同时要把gmes_linux所在目录导出为环境变量GENEMARK_PATH。如果BRAKER2运行时报"can not execute gmes_petap.pl"或"gm_key not found"，90%是这两处配置不对。

BRAKER2主程序下载也很简单：

cd ~/biosoft git clone https://github.com/Gaius-Augustus/BRAKER.git

然后只需要两步：把~/biosoft/BRAKER/scripts加进PATH，把~/biosoft/BRAKER/scripts导出为PERL5LIB。到这一步，源码路线的安装工作基本结束，接下来是配置环节。

如果你选择了conda路线，第3节的这些内容可以跳过一半，但第4节不可以跳。

4. 环境变量、权限和路径：安装完成后最容易翻车的环节

不管conda还是源码装，以下环境变量都是BRAKER2能跑起来的先决条件。我建议把下面这段写进~/.bashrc：

# BRAKER2 export BRAKER2=~/biosoft/BRAKER export PATH=$PATH:$BRAKER2/scripts export PERL5LIB=$PERL5LIB:$BRAKER2/scripts # Augustus export AUGUSTUS_CONFIG_PATH=~/biosoft/Augustus/config export AUGUSTUS_BIN_PATH=~/biosoft/Augustus/bin export AUGUSTUS_SCRIPTS_PATH=~/biosoft/Augustus/scripts export PATH=$PATH:$AUGUSTUS_BIN_PATH:$AUGUSTUS_SCRIPTS_PATH # GeneMark export GENEMARK_PATH=~/biosoft/gmes_linux export PATH=$PATH:$GENEMARK_PATH

这几个变量缺一个，运行braker.pl时都会出现"说得清又说不清"的报错。比如有人which augustus能看到工具，但BRAKER2训练时就是找不到Augustus的配置目录，通常就是因为AUGUSTUS_CONFIG_PATH没设置，或者设置后没执行source ~/.bashrc。

关于写权限，这是最容易忽视的坑。BRAKER2会调用Augustus的new_species.pl来创建当前物种的配置目录，这个动作非得在config目录下有写权限才能执行。如果你是在共享服务器上，其他人装的Augustus config目录可能只有只读权限，那就要自己单独拷贝一份config目录到自己的路径，再指向它：

cp -r ~/biosoft/Augustus/config ~/biosoft/Augustus/config_my chmod -R a+w ~/biosoft/Augustus/config_my export AUGUSTUS_CONFIG_PATH=~/biosoft/Augustus/config_my

权限问题通常不是因为故意设置，而是系统用户权限隔离的原因。初期排查BRAKER2报错时，先自查这三件事：AUGUSTUS_CONFIG_PATH有没有指向实际存在的目录、这个目录可不可写、.gm_key在不在主目录。

5. 用官方测试数据跑一遍，验证安装没白费

环境配置完之后，不要急着跑自己的基因组，先用BRAKER2自带测试数据或者一套小型的测试基因组验证一下。这样做的好处是：报错了可以排除"是我的数据有问题"这个干扰项，先把安装层面的问题清干净。

5.1 测试流程与参数解释

BRAKER2测试数据可以单独下载官方示例，或者去BRAKER仓库的example目录找。我习惯自备一份小型基因组fasta和对应的RNA-seq比对BAM文件。推荐一个最小测试方式：

cd ~/biosoft/BRAKER/test braker.pl --genome=genome.fa --bam=RNAseq.bam --species=mybrakertest \ --softmasking --gff3 --cores=8

这条命令里每个参数都值得记牢：

• --genome=genome.fa：参考基因组，建议是重复序列已经被掩蔽过的版本
• --bam=RNAseq.bam：RNA-seq reads比对到同一参考基因组后得到的BAM文件，必须已按坐标排序
• --species=mybrakertest：给当前注释项目起的物种名，Augustus会专门为这个物种名建立参数集，每次注释不同物种时不要重复使用同一个名字
• --softmasking：表示输入基因组采用软掩蔽方式，重复区段用小写字母而不是N表示，让预测器既能识别重复区域又保留其原始信息
• --gff3：输出GFF3格式
• --cores=8：多线程数量，根据机器核数调整

如果你的数据是蛋白组而不是RNA-seq，可以用--prot_seq=proteins.fa替代--bam，BRAKER2会走同源注释路线。

运行时间取决于基因组大小、BAM深度和核心数。小测试基因组几分钟就能完成。

5.2 输出文件怎么读

跑完后，结果默认在当前目录下一个以物种名命名的子目录里，比如~/biosoft/BRAKER/test/mybrakertest/。里面最重要的几个文件：

• braker.gff3：最终的基因结构注释文件，GFF3格式，包含mRNA、CDS、exon等特征
• braker.aa：预测的蛋白序列，FASTA格式
• braker.codingseq：预测的CDS序列
• augustus.gff3：Augustus阶段的中间输出，发现braker.gff3异常时可以对照看
• GeneMark-ET或etp相关目录：GeneMark的训练和预测中间结果

拿到braker.gff3后，我通常会先数一下预测基因数量，跟相近物种的基因数量做粗略对照。如果数量明显离谱，比如一个40Mb真菌基因组预测出10万个基因，那大概率是训练环节出了问题，而不是安装问题。

6. 实测踩坑记录：从报错到定位的完整链路

这里记录几类我实际装BRAKER2时遇到过的报错，按排查思路写，不是简单贴一条答案。

6.1 bamtools的动态库找不到

运行braker.pl后很快报错：

error while loading shared libraries: libbamtools.so.2.5.1: cannot open shared object file

这种报错说明Perl脚本调用bamtools相关模块时，动态库路径没被程序找到。我当时的排查思路是：先用ldconfig -p | grep bamtools查系统有没有把bamtools库注册进去，发现没有，于是直接用LD_LIBRARY_PATH指过去：

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/bamtools

如果你的bamtools是conda装的，库路径通常在conda环境的lib目录下，同样用LD_LIBRARY_PATH指过去。

排查这类问题有个通用逻辑：先确认二进制在哪个目录，再确认它依赖什么库，然后用ldd命令逐个查：

ldd $(which bamToWig)

ldd输出里有显示"not found"的，就是需要补路径或安装的库。

6.2.gm_key许可证缺失报错

报错信息类似：

GeneMark cannot be executed. The run failed at the point when it was executing the GeneMark-ES/ET self-training.

这个报错的本质是GeneMark的许可文件没被正确放置，或者GENEMARK_PATH没有指向gmes_linux目录。我遇到时第一步先检查：

ls -l ~/.gm_key

如果没有文件，就把下载好的key放过去；如果有，再看权限，-rw-------才算正常。还有一种情况是.gm_key存在但内容不完整，下载邮件里复制key内容时漏了末尾的换行或中间某一行。解决方法是重新完整复制一次许可内容。

6.3 Perl模块路径缺失

报错：

Can't locate strict vars.pm in @INC (you may need to install the strict vars module)

或者更常见的：

Can't locate module B::Hooks::EndOfScope

BRAKER2的Perl脚本依赖一批CPAN模块。源码安装方式下，别忘了把$BRAKER2/scripts加入PERL5LIB，因为很多模块就是自带在scripts目录里的。就算加了还报某个module缺失，再用cpanm补装对应模块，而不是气急败坏重装整个BRAKER2。下面是我常用的定制命令：

perl -MCPAN -e 'install B::Hooks::EndOfScope'

conda安装方式下，这类报错比较少，因为bioconda已经把所有perl依赖都打包进去了。如果你用conda装还是报Perl模块缺失，大概率是环境混了：braker.pl实际调用的是base环境的Perl，而不是braker2环境里的Perl。用which perl确认一下，路径必须在braker2环境内。

6.4 Augustus写config目录失败

运行中报：

ERROR: The config directory /home/user/biosoft/Augustus/config does not exist or is not readable

或者跑到某一步提示没法创建物种目录。这个就是权限问题，按第4节的方法把config目录拷贝出来并放开写权限即可。还有一种隐藏情况：AUGUSTUS_CONFIG_PATH写得不对，BRAKER2在后台调用Augustus时根本没拿到这个环境变量。排查办法是直接在命令行里再看一遍：

echo $AUGUSTUS_CONFIG_PATH

如果输出是空，说明~/.bashrc里那行没生效，重新执行source ~/.bashrc，或者干脆从终端手动export后再跑测试。

7. 从装完到投产：真正跑基因组的几个建议

测试跑通只是第一步，真到了自己的项目上，有几个点我建议提前想清楚。

输入基因组最好先做重复序列掩蔽。BRAKER2对未掩蔽基因组也能跑，但结果里会混入大量转座子相关预测，导致基因数量虚高。我会用RepeatMasker对组装基因组做一遍soft masking，小写字母表示重复区域，然后再交给BRAKER2，参数里保持--softmasking。

如果打算用RNA-seq辅助注释，BAM文件的质量比数量重要。比对工具用hisat2或STAR都可以，关键是比对完要按坐标排序并建立索引：

samtools sort -@ 8 -o rnaseq.sorted.bam rnaseq.unsorted.bam samtools index rnaseq.sorted.bam

BRAKER2对BAM文件的要求就是sorted+indexed，少了索引会报错或行为异常。

关于蛋白库的选择，如果走--prot_seq路线，建议选覆盖度高的参考蛋白库，比如OrthoDB的相应类群子集，或者直接准备近缘物种的蛋白组。蛋白库不需要太大，太杂反而增加spaln和diamond的比对负担，拖慢整个流程。

输出结果也不是终点。我拿到braker.gff3后，还会用BUSCO对预测蛋白序列做一次完整性评估，看核心单拷贝基因找回比例。这一步能快速判断注释质量，如果BUSCO完整率远低于同类已有物种，先别急着调参，检查输入BAM和蛋白库可能更有效。

最后，如果你是在集群或容器环境里跑，建议把整个安装环境打包成镜像或者固定conda环境导出文件。BRAKER2的依赖链太长了，几个月后换机器重装，很容易因为某个工具版本不同而出现行为差异。我用conda env export > braker2_env.yml把环境完整记录下来，换机器时一次性重建，省心得多。