⚡ Benchmark numbers are hidden pending re-measurement — the distribution's feature set has changed since they were last measured (2026-09-06).
This is a downstream build of lh3/minibwa. It carries changes upstream declined, plus a few not yet offered. Upstream remains the source of truth for everything else.
Install from a release tag, not from a branch. Tags such as
v0.6-nh13.1are immutable; thedistbranch is rebuilt and force-pushed on every upstream change and will rewind under you.minibwa versionreports the downstream version, and it appears in the@PG VN:tag of every SAM file this build writes, so output is always traceable to the build that produced it.Bug reports for anything in the table below belong here, not upstream. Changes investigated and deliberately not shipped are in
GRAVEYARD.md.
| feature | upstream | status | output | summary |
|---|---|---|---|---|
ops-distro |
— | unsubmitted | identical | distribution manifest, assembly engine and workflows |
ll-affine-reassoc |
lh3/minibwa#37 | rejected | identical | reassociate the affine-gap recurrence in ksw2_ll for arm64 |
ksw2-extension-kernels |
lh3/minibwa#64 | open | identical | shuffle-LUT prepass, one-vext rail shift, 16-wide exact-max and NEON BIT direction bytes in ksw2_extd2/extz2; +11% HiFi and +10% ONT on arm64, +7% on x86 |
single-copy-parser |
— | unsubmitted | identical | read FASTQ records with a single copy instead of two; 0.67-1.24 pp whole-stack ladder increment |
index-threads-v2 |
— | unsubmitted | identical | parallelize the SA-to-BWT pipeline (OpenMP, gated on the existing LIBSAIS_OPENMP probe) |
extd2-avx512 |
lh3/minibwa#20 | open | identical | AVX2/AVX-512 ksw_extd2 with runtime dispatch; pays on HiFi/ONT |
radix-key-width |
— | unsubmitted | identical | right-size klib radix key widths -- 5-byte genome-coordinate and 4-byte int32 chain-score sorts; byte-identical, 1.5-4.9x per-sort but <~1% of map CPU |
inline-appenders |
lh3/minibwa#32 | rejected | identical | format SAM/PAF records with inline appenders; with parallel-encode worth +3.7 pp at the default -K on wgs-1M but ~0 above ~10M pairs (input-size dependent, see notes) |
parallel-encode |
lh3/minibwa#33 | open | identical | format SAM/PAF in the mapping step instead of the output thread; relocates work rather than removing it, so it pays only on inputs small enough to be starvation-bound |
meth-cleanups |
lh3/minibwa#19 | rejected | identical | a --meth CI test; documents the mb_align1_inv strand flip and b_ts (comments only) |
meth-sam-tags |
lh3/minibwa#15 | open | conditional | emit Bismark-compatible XR/XG/XM tags |
soft-clip-penalty |
lh3/minibwa#13 | rejected | conditional | 5'/3' soft-clip penalty (-L) |
submem-ablation |
lh3/minibwa#12 | rejected | conditional | expose --max-sub-occ and --min-sub-occ ablation flags |
sa-default-u3 |
— | unsubmitted | identical | default the SA sample rate to 1/8 (-u 3); ~5-6% faster mapping for ~+3 GB RAM on hg38, all native densities byte-identical |
sa-regime-picker |
— | unsubmitted | identical | --index-regime picker with auto speed/memory selection over byte-identical native SA densities (--index-mem, --list-regimes) |
cp-occ-backend |
— | unsubmitted | conditional | compile-optional cp_occ (bwa-mem2/mem3 FM-index) seeding backend (make B2=1); ~5-12% faster at matched density, differs from native for ~0.05% of reads (MAPQ-0 multimappers) |
sa-batch-128 |
— | unsubmitted | identical | raise the SA-lookup batch depth in mb_anchor 20 -> 128 so more SA walks overlap; +1.9% WGS / +3.9% HiFi on arm64, +0.5% on x86 AVX2 |
alt-liftgroup |
— | unsubmitted | conditional | ALT-aware mapping via post-extension liftover groups |
git clone https://github.com/lh3/minibwa
cd minibwa && make
# with test data
./minibwa index test/chrM-human.fa.gz chrM-human # index the genome
./minibwa map chrM-human test/chrM-read_?.fa.gz > aln.sam # align and output in SAM
# other examples without test data
minibwa map -ft16 ref.index long-read.fq > aln.paf # align long reads
minibwa map --hic ref.index reads.interleaved.fq > aln.sam # align Hi-C short reads
# align *directional* bisulfite sequencing (BS-seq) reads
minibwa index --meth -t8 ref.fa # generate BS-seq index
minibwa map --meth ref.fa read1.fq read2.fq > aln.sam # map BS-seq readsMinibwa aligns short reads against a reference genome. It is the successor of bwa-mem with a different algorithm. Minibwa is over three times as fast as the original bwa-mem and twice as fast as bwa-mem2 at comparable accuracy. While minibwa works with accurate long reads, minimap2 is more robust under high error rate.
Minibwa is a hybrid of bwa-mem and minimap2: it indexes the genome with Burrow-Wheeler Transform (BWT), finds variable-length seeds like bwa-mem, and performs chaining and SIMD-based nucleotide alignment with the minimap2 algorithm. Minibwa speeds up bwa-mem2 further with additional prefetch for seeding, new heuristics to skip unnecessary mate rescue and reduced effort in highly repetitive regions where reads would often be wrongly mapped due to structural changes anyway.
Minibwa is designed for mapping short reads and accurate long reads. It does
not support spliced alignment and has not been tuned for aligning long contigs.
Alternate contigs are supported: when a <idx>.alt file sits beside the index
it is loaded automatically and ALT hits are reconciled with their primary
counterparts, so an ALT twin no longer collapses the primary's mapping quality.
Pass --no-alt to ignore it and align exactly as if no ALT file existed.
Minibwa requires either SSE4.2 on x86 CPUs or NEON on ARM. It depends on zlib installed on your system and also includes slightly modified source code of mimalloc and libsais which optionally uses OpenMP for multi-threading. You can build minibwa with
make # automatically detect OpenMP and arm64 vs. x86_64
make omp=0 # disable multi-threading in libsais (no effect on mapping)
make gpl=0 # disable GPL'd code for low-memory BWT building (no effect on mapping)
make mimalloc=0 # disable mimalloc and use the system malloc+kalloc insteadThis produces a single binary minibwa which you can copy to your PATH.
Like bwa-mem, minibwa requires to index the genome before read alignment.
You can index the reference genome with
minibwa index -t8 ref.fa # index with 8 threads, using 18N RAM (N is the genome size)
minibwa index ref.fa prefix # use a different index prefix instead of ref.fa
minibwa index -l ref.fa # use less memory at the cost of performance
minibwa index --meth ref.fa # generate BS-seq indexminibwa samples the suffix array at 1/8 by default (
-u 3). Mapping is ~12% faster in the mapping phase on hg38 (measured: 1/8 is 1.12× the 1/16 map-phase throughput); the index and peak RAM grow by ~3 GB (≈9 → ≈12 GB). Build withminibwa index -u 4for the previous 1/16 index (smaller, ~12% slower). Denser than 1/8 (-u 2/-u 1) is not recommended for routine use: the speed gain flattens sharply (≈1.19–1.23×) while RAM grows 2–6×, so the extra memory buys little.
Minibwa generates two files: ref.fa.l2b for 2-bit encoded reference genome
sequences and ref.fa.mbw for BWT and sampled suffix array. In the --meth
mode, minibwa additionally generates ref.fa.meth.mbw for the BWT of the
3-base genome.
By default, minibwa dynamically changes multiple internal parameters based on individual read lengths. It works for both short and accurate long reads.
minibwa map -t8 ref.fa read1.fq read2.fq # map paired-end reads and output SAM
minibwa map -ft8 ref.fa read.fa.gz # map single-end or long reads; output PAF
minibwa map --hic ref.fa hic1.fq hic2.fq # map Hi-C short reads
minibwa map --meth ref.fa read1.fq read2.fq # map BS-seq reads; requiring "index --meth"Note in the default adaptive mode, -g/-w/-W/-N/-m/-s only changes
the short-read setting; the long-read setting is fixed. This mode is disabled
with --adap=no or when -x sr or -x lr is specified.
Minibwa also provides legacy bwa-mem command-line interface (CLI) via the mem subcommand
63E7
.
However, due to algorithm and parameter differences, many bwa-mem options are ignored.
The output minibwa alignment is also not identical to bwa-mem.
Minibwa provides basic APIs for loading index and aligning reads. api-test/ex-one.c shows an example to align each read independently; api-test/ex-batch.c aligns multiple reads in batch, which is faster and also supports paired-end mapping. dev.md explains how minibwa differs from BWA-MEM and minimap2.
Minibwa is distributed under the MIT license. It also incorporates source code from the following projects:
- libsais: Apache 2 License. Copyright (c) 2021-2025 Ilya Grebnov
- mimalloc: MIT License. Copyright (c) 2018-2026 Microsoft Corporation, Daan Leijen
The master branch is optionally built on the following projects:
- QSufSort: HPND License. Copyright (c) 1999 N. Jesper Larsson
- bwtgen: GPL 2 License. Copyright (c) 2004 Wong Chi Kwong
Notably, the master branch includes GPL'd bwtgen.c for low-memory
BWT construction. If you compile this file, which is the default, the resulting
binary will be GPL'd. You can disable the low-memory algorithm with make gpl=0 to generate non-GPL binary. The Apache2 branch does not
include GPL'd source code.
- Minibwa does not work with noisy long reads or spliced RNA-seq reads.
- Minibwa does not support undirectional bisulfite sequencing data.