# minimap2: genomic sequence aligner for PacBio and Oxford Nanopore long reads

> minimap2 is a C aligner for genomic and spliced nucleotide sequences, covering long reads from PacBio and Oxford Nanopore, short Illumina reads, assembly comparison and RNA-seq. Speed figures cited in the README come from peer-reviewed papers, not from self-reported benchmarks.

**lh3/minimap2** — A versatile pairwise aligner for genomic and spliced nucleotide sequences

- Repository: https://github.com/lh3/minimap2
- Website: https://lh3.github.io/minimap2
- Stars: 2,258 · Forks: 480
- Language: C
- License: NOASSERTION
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/lh3-minimap2

## Six alignment tasks minimap2 covers and the read types it addresses

minimap2 aligns DNA or mRNA sequences against a large reference database. The README enumerates six primary use cases: mapping PacBio or Oxford Nanopore genomic reads to the human genome, finding overlaps between long reads with error rates up to approximately 15%, splice-aware alignment of PacBio Iso-Seq or Nanopore cDNA or Direct RNA reads against a reference genome, aligning Illumina single-end or paired-end reads, assembly-to-assembly alignment, and full-genome alignment between two closely related species with divergence below approximately 15%.

Those six cases span very different data types. A short-read aligner handles only the fourth; minimap2 uses presets to switch between the others without requiring a different binary. That design choice means one tool covers the typical stages of a long-read sequencing project, from initial read mapping through transcript analysis and final assembly comparison.

The speed figures the README cites come from two published sources, the minimap2 paper and the preprint linked in the document. For approximately 10kb noisy reads, the README reports tens of times faster than BLASR, BWA-MEM, NGMLR and GMAP. For Illumina reads longer than 100bp, it reports three times faster than BWA-MEM and Bowtie2, with accuracy described as comparable on simulated data. The accuracy qualifier matters: the claim applies to simulated reads, not to benchmarks on real sequencing data from any specific instrument run.

## Installing from the v2.31 precompiled binary or building from source with make

Precompiled x86-64 Linux binaries are available from GitHub. Downloading and extracting v2.31:

```sh
curl -L https://github.com/lh3/minimap2/releases/download/v2.31/minimap2-2.31_x64-linux.tar.bz2 | tar -jxvf -
./minimap2-2.31_x64-linux/minimap2
```

To build from source, the prerequisites are a C compiler, GNU make and zlib development files. Cloning and building:

```sh
git clone https://github.com/lh3/minimap2
cd minimap2 && make
```

If SSE4 is unavailable on older hardware, adding sse2only=1 disables it at a small speed cost. For ARM CPUs that support NEON, `make arm_neon=1` handles 32-bit ARMv7 targets and `make arm_neon=1 aarch64=1` handles 64-bit ARMv8. The Makefile also supports sanitizers: asan and tsan are available as build-time flags for development and testing.

Porting to non-x86 and non-ARM SIMD instruction sets goes through the SIMD Everywhere (SIMDe) library. Running `make -f Makefile.simde` produces that build, with the same ARM flags applicable on top of it.

One warning that appears prominently in the README: minimap2.com is a phishing site. The project has no official website at that domain; binaries and documentation come from the GitHub release page and from https://lh3.github.io/minimap2.

## Presets for map-ont, map-pb, map-hifi, splice and sr: how alignment modes are selected

minimap2 selects alignment parameters through preset names passed with -x or -ax. The README shows the main presets with their corresponding read types:

```sh
./minimap2 -ax map-ont ref.fa ont.fq.gz > aln.sam         # Oxford Nanopore genomic reads
./minimap2 -ax map-pb ref.fa pacbio.fq.gz > aln.sam       # PacBio CLR genomic reads
./minimap2 -ax map-hifi ref.fa pacbio-ccs.fq.gz > aln.sam # PacBio HiFi/CCS genomic reads (v2.19+)
./minimap2 -ax lr:hq ref.fa ont-Q20.fq.gz > aln.sam       # Nanopore Q20 genomic reads (v2.27+)
./minimap2 -ax splice ref.fa rna-reads.fa > aln.sam       # spliced long reads
./minimap2 -ax sr ref.fa read1.fa read2.fa > aln.sam      # short genomic paired-end reads
./minimap2 -ax splice:sr ref.fa r1.fq r2.fq > aln.sam     # short-read RNA-seq (v2.29+)
```

The -a flag requests SAM output. Without any alignment flag, the output is PAF format with only approximate coordinates and no CIGAR string. Adding -c to a PAF-mode run produces CIGAR at the cg tag. The choice of output format and preset must match the downstream tools in the pipeline: a caller that expects SAM needs -a, and a caller that expects PAF works with the default.

minimap2 accepts gzip-compressed FASTA and FASTQ directly, without requiring decompression or format conversion before the alignment step.

## Saving an index with -d and the parameters that cannot change after indexing

For large reference genomes, building the minimizer index takes several minutes on the first run. Saving that index to a file avoids repeating the build:

```sh
minimap2 -d ref.mmi ref.fa
minimap2 -a ref.mmi reads.fq > alignment.sam
```

The README is explicit about a constraint this introduces. Once an index is built, the indexing parameters -k, -w, -H and -I cannot be changed during subsequent mapping runs against that index. If different data types require different parameter values, separate index files are necessary.

The README names this as a difference from BWA, which uses the same index regardless of query type. In a workflow that handles both ONT reads and PacBio reads against the same reference, two separate minimap2 index files cover the two presets. Managing those extra files is a recurring cost absent from BWA-based pipelines.

The index file extension in the README examples is .mmi. Nothing in the available documentation describes whether .mmi files are forward-compatible across minimap2 major versions; rebuilding the index after a version upgrade is the safe path.

## mappy: Cython build requirements and conflicting metadata in setup.py

minimap2 exposes a Python binding called mappy, which requires setuptools, wheel and Cython to build, as listed in pyproject.toml. The Cython requirement means pip install involves a compilation step rather than fetching a pre-built wheel.

setup.py declares `license = 'MIT'` with an OSI Approved MIT classifier, but the GitHub repository classifies the licence as Other (a custom licence GitHub cannot classify); anyone redistributing the mappy package should read LICENSE.txt rather than relying on setup.py's declaration.

setup.py also includes Python 2.7 in its classifier list. Whether the build works on Python 2.7 is not confirmed elsewhere in the documentation. The platform-specific compile flags show up in setup.py's logic: x86_64 builds add -msse4.1, while aarch64 and arm64 builds use the sse2neon headers instead.

## BWA-MEM as the performance baseline: what the speed figures cover and where they stop

BWA-MEM is the primary short-read aligner the README uses as a comparison. For Illumina short reads longer than 100bp, the README reports minimap2 runs three times faster than BWA-MEM and Bowtie2, with accuracy described as comparable on simulated data. For long noisy reads around 10kb, the comparison expands to BLASR, NGMLR and GMAP, and the reported speed advantage is tens of times.

Those figures come from the minimap2 paper and preprint, not from a benchmark the README reproduces. The 'simulated data' qualifier appears both times accuracy is mentioned for short reads. Any assessment of accuracy on real sequencing data from a specific instrument or laboratory protocol requires testing against that data.

The architecture difference is what makes BWA-MEM unsuitable as a long-read aligner: it was designed for short reads and does not handle the error rates characteristic of ONT or PacBio CLR reads. minimap2 addresses that gap by supporting higher error tolerances through its preset system. For short-read Illumina workflows already built around BWA-MEM, switching to minimap2 adds the index-per-data-type management cost described in the previous section, without a clear accuracy advantage on real data.

## Assembly comparison with asm5, overlap detection and the annotation junction option

Beyond read mapping, two additional use cases in the README cover stages that come later in an assembly workflow. The asm5 preset aligns two assemblies against each other:

```sh
./minimap2 -cx asm5 asm1.fa asm2.fa > aln.paf
```

Outputting PAF here is typical because the downstream tools for assembly comparison often expect that format. The asm5 preset is described as targeting intra-species comparisons.

For overlap detection between long reads, two presets are available:

```sh
./minimap2 -x ava-pb reads.fa reads.fa > overlaps.paf  # PacBio read overlap
./minimap2 -x ava-ont reads.fa reads.fa > overlaps.paf # Nanopore read overlap
```

For splice-aware alignment with known junctions, the README shows a `--junc-bed` option that accepts a BED12 file:

```sh
./minimap2 -ax splice --junc-bed=anno.bed12 ref.fa query.fa > aln.sam
```

Short-form `-j anno.bed12` is equivalent. Providing annotated junctions is optional but can improve splice-site accuracy for transcriptome alignments where a high-quality annotation exists. The README does not document what happens when a junction in the BED12 file conflicts with the alignment evidence.

## Conclusion

minimap2 suits genomic workflows mapping long reads from PacBio or Oxford Nanopore devices, where its speed advantage over BLASR, BWA-MEM, NGMLR and GMAP is documented in the papers cited in the README. For Illumina short-read work already in BWA-MEM pipelines, the main trade-off is managing a separate minimap2 index per data type rather than one universal index. Confirm your platform before building (x86-64 has the best-tested path), treat the speed figures in the README as summaries of peer-reviewed data, and if multiple data types feed the same pipeline, build a separate index with -d for each preset before the first production run.

## FAQ

### What is minimap2 used for?

minimap2 aligns DNA or mRNA sequences against a reference database. Its six documented use cases include mapping PacBio and Oxford Nanopore long reads to a reference genome, splice-aware alignment of Iso-Seq and Nanopore cDNA reads, aligning Illumina short reads, assembly-to-assembly comparison and long-read overlap detection.

### How do I install minimap2?

Precompiled x86-64 binaries for v2.31 are on the GitHub release page and can be downloaded with curl. To build from source, clone the repository and run make; you need a C compiler, GNU make and zlib headers. For ARM CPUs, make arm_neon=1 targets ARMv7 and make arm_neon=1 aarch64=1 targets ARMv8.

### What is the difference between minimap2 and BWA-MEM?

minimap2 handles long noisy reads from PacBio and Oxford Nanopore, which BWA-MEM does not support well. For Illumina short reads, the README reports minimap2 runs three times faster than BWA-MEM on simulated data. Unlike BWA, minimap2 requires a separate index for each data type when multiple presets are used.

### Does minimap2 have a Python API?

Yes, through a package called mappy. Version 2.31 of mappy is in setup.py and requires Cython to build. The package is listed on PyPI.

### What output formats does minimap2 produce?

Without options, minimap2 outputs PAF with approximate coordinates and no CIGAR string. Adding -c produces CIGAR in the PAF cg tag. Adding -a produces SAM format.

## Sources

- [Issues](https://github.com/lh3/minimap2/issues)
- [lh3/minimap2 on GitHub](https://github.com/lh3/minimap2)
- [Project website](https://lh3.github.io/minimap2)
- [README](https://github.com/lh3/minimap2/blob/master/README.md)
- [Releases](https://github.com/lh3/minimap2/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lh3-minimap2