⚡ 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-reassoclh3/minibwa#37 rejected identical reassociate the affine-gap recurrence in ksw2_ll for arm64 ksw2-extension-kernelslh3/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-avx512lh3/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-appenderslh3/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-encodelh3/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-cleanupslh3/minibwa#19 rejected identical a --meth CI test; documents the mb_align1_inv strand flip and b_ts (comments only) meth-sam-tagslh3/minibwa#15 open conditional emit Bismark-compatible XR/XG/XM tags soft-clip-penaltylh3/minibwa#13 rejected conditional 5'/3' soft-clip penalty (-L) submem-ablationlh3/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>.altfile 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-altto 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
minibwawhich you can copy to yourPATH.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.l2bfor 2-bit encoded reference genome sequences andref.fa.mbwfor BWT and sampled suffix array. In the--methmode, minibwa additionally generatesref.fa.meth.mbwfor 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/-sonly changes the short-read setting; the long-read setting is fixed. This mode is disabled with--adap=noor when-x sror-x lris specified.Minibwa also provides legacy bwa-mem command-line interface (CLI) via the
memsubcommand. 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=0to 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.
