pyminimap2: a Python wrapper for minimap2

pyminimap2 is a Python wrapper for minimap2 (developed by Heng Li). pyminimap2 generates exactly the same output as minimap2 as it simply pass the command-line arguments to the main function in main.c of minimap2.

Compared to invoking minimap2 through subprocess.run or os.system(), using pyminimap2 incurs significantly lower overhead.

In our benchmark, running pyminimap2.main('--version') is approximately 20–30 times faster than invoking minimap2 --version using subprocess.run, and about 40 times faster than calling it via os.system().

pyminimap2 is a good choice for applications requiring frequent or high-throughput invocations of minimap2 from within Python.

How to install

Option 1: Install via pip (Recommended)

We provide pre-compiled binaries for Linux and Python versions 3.9 to 3.13. Simply run the following command:

pip install pyminimap2

Option 2: Clone and compile from source

git clone --recursive https://github.com/TheFangLab/pyminimap2.git
cd pyminimap2
pip install .

Choose this option if you are using Python 3.14 or a later version. You need to have a C compiler (e.g. GCC).

How to use

Assuming your orignal command for executing minimap2 is

minimap2 -x map-ont ref.fa read.fq.gz

You can use pyminimap2 as follows:

import pyminimap2 as pymm2
out, err = pymm2.main("-x map-ont ref.fa read.fq.gz")

This would generate the exact same output as minimap2 -x map-ont ref.fa read.fq.gz.

If you want to save the output to a file, you can use the -o option (same as the -o option of minimap2):

out, err = pymm2.main("-x map-ont ref.fa read.fq.gz -o output.paf")

This would generate a output.paf file.

In summary, if you use -o to specify the output file, pyminimap2 will generate the same output file as minimap2. If -o is not specified, pymm2.main() returns a tuple (out, err) where out contains the stdout and err contains the stderr.

You can find explainations of the command-line arguments of minimap2 at

1. https://github.com/lh3/minimap2
2. https://lh3.github.io/minimap2/minimap2.html

Difference from mappy

1. Access to the Full Command-Line Interface (CLI).

pyminimap2 accepts exactly the same command-line arguments as minimap2. Everything minimap2 can do via CLI is available.

2. Identical Output

pyminimap2 generates exact the same output as minimap2. If you are running existing pipelines that rely on parsing standard PAF or SAM files generated by the CLI tool, pyminimap2 creates strictly identical text output (stdout) or files.

mappy requires a deeper understanding of the Python API (such as mappy.Aligner and mappy.Alignment).

3. Low Migration Friction

If you have existing scripts using subprocess.run or os.system() to call minimap2, migrating to pyminimap2 is almost trivial. You just pass the specific string of arguments you were already using.

About version

You can use the following code to print the version number of minimap2 bound in pyminimap2:

import pyminimap2 as pymm2
print(pymm2.main('--version')[0])

Maintainers

pyminimap2 is currently maintained by Li Fang at Sun Yat-sen University. For issues and feature requests, please open an issue here.

Acknowledgments

• Heng Li, original author and maintainer of minimap2.
• All contributors to the minimap2 project.

License

pyminimap2 is released under the MIT license.