bwamem

Python bindings for the BWA-MEM aligner.

Installation

pip install bwamem

Usage

Build Index

from bwamem import BwaIndexer

indexer = BwaIndexer()
index_path = indexer.build_index('reference.fa')

Single-End Alignment

from bwamem import BwaAligner

aligner = BwaAligner('path/to/index')
alignments = aligner.align('ACGATCGCGATCGA')

for aln in alignments:
    print(f'{aln.ctg}:{aln.r_st} strand={aln.strand} mapq={aln.mapq}')

Paired-End Alignment

read1 = 'ACGATCGCGATCGA'
read2 = 'TTCGATCGATCGAT'

paired_alignments = aligner.align(read1, read2)

for pe_aln in paired_alignments:
    print(f'Insert size: {pe_aln.insert_size}, Proper pair: {pe_aln.is_proper_pair}')

Retrieve Sequences from Index

# Get full sequence
seq = aligner.seq('chr1')

# Get subsequence
subseq = aligner.seq('chr1', start=100, end=200)

Monitor Index Building Progress

from bwamem import BwaIndexer

# Progress messages are captured by default (no console spam)
indexer = BwaIndexer(capture_progress=True)
index_path = indexer.build_index('genome.fasta')

# Check progress info
progress = indexer.get_progress()
print(f"Status: {progress['status']}")
print(f"Iterations: {progress['iterations']}")
print(f"Characters processed: {progress['characters_processed']}")

# Get progress percentage (if available)
if indexer.progress_percent:
    print(f"Progress: {indexer.progress_percent:.1f}%")

# Access all captured messages
for msg in progress['messages']:
    print(msg)

Control Index Building Verbosity

from bwamem import BwaIndexer

# Verbosity levels:
# 0 = silent (no output)
# 1 = quiet (only warnings/errors) - default
# 2 = normal (standard BWA messages)
# 3+ = debug (verbose output)

# Silent mode
indexer = BwaIndexer(verbose=0)
indexer.build_index('genome.fasta')

# Normal mode with progress messages shown in console
indexer = BwaIndexer(verbose=2, capture_progress=False)
indexer.build_index('genome.fasta')

# Debug mode with captured progress
indexer = BwaIndexer(verbose=3, capture_progress=True)
indexer.build_index('genome.fasta')

# Custom algorithm and block size
indexer = BwaIndexer(algorithm='bwtsw', block_size=50000000)
indexer.build_index('genome.fasta')

Read FASTA/FASTQ Files

from bwamem import fastx_read, read_paired_fastx

# Single-end (supports both FASTA and FASTQ)
for read in fastx_read('sequences.fasta.gz'):
    print(f'{read.name}: {read.sequence}')

# Paired-end
for read1, read2 in read_paired_fastx('R1.fastq', 'R2.fastq'):
    print(f'{read1.name}, {read2.name}')

Custom Options

# Specify alignment parameters
aligner = BwaAligner('path/to/index', options='-x ont2d -A 1 -B 0')

# Set custom insert size for paired-end reads
aligner = BwaAligner('path/to/index', insert_model=(500, 50))
paired_alignments = aligner.align(read1, read2)

Command-line tool

bwamem map runs BWA-MEM against one or more reference layers and emits a SAM stream annotated with a HI:Z:<layer> tag used for hierarchical / contamination-aware assignment:

# Single-end, hierarchical (contamination -> genes -> transcripts)
bwamem map -i contamination -i genes -i tx_transcript \
    -k 18,14,10 -n 0.05,0.15,0.30 -T 30,30,30 reads.fq

# Paired-end against a single reference
bwamem map -i ref -1 r1.fq.gz -2 r2.fq.gz -o out.sam

HI:Z:<i> records which layer claimed each read (0-based); reads that map to no layer get HI:Z:-1 (these are the candidates forwarded to the genome stage). Each layer's parameters (-k, -n, -T) may be given as a single value applied to all layers or a comma-separated list, one per layer.

Parallelism (`-t / --threads`)

Alignment is parallelized across processes (fork, COW-shared index), not threads, so the C alignment runs concurrently without holding the GIL:

bwamem map -t 8 -i ref -1 r1.fq.gz -2 r2.fq.gz

Single-threaded output is byte-identical to the parallel output. Because input parsing is streamed lazily through a bounded buffer, memory stays bounded regardless of input size.

-t 1 (the default) keeps the historical single-process code path unchanged.

SE primary-hit determinism

For single-end reads that have perfectly tied, equal-scoring alignments (identical score / mapq / CIGAR / layer), BWA's mem_align1 does not mark a deterministic primary (the SE path — unlike the paired-end path — never calls mem_mark_primary_se). As a result, the exact repeat-scaffold coordinate reported for such reads can depend on process-internal state, and may differ between runs or between the process path and fork workers.

This affects only the reported repeat position of a tiny fraction of multi-mapper reads: the HI:Z:<layer> assignment, mapped/unmapped status, score, mapq and CIGAR are all unaffected. Pipelines that consume the SAM by HI:Z layer (e.g. the small_RNA genome-vs-not decision) are therefore unaffected. This is pre-existing BWA behavior, not introduced by the parallel path.

Alignment Attributes

Each Alignment object contains the following attributes:

Attribute	Description
`ctg`	Contig/reference name
`r_st`	Reference start position (0-based)
`r_en`	Reference end position (property)
`strand`	Strand: +1 for forward, -1 for reverse
`q_st`, `q_en`	Query start/end positions
`mapq`	Mapping quality score
`cigar`	CIGAR as list of `[length, op]` pairs
`cigar_str`	CIGAR string (property)
`NM`	Edit distance
`score`	Alignment score
`is_primary`	Primary alignment flag

Calculated properties (computed on demand): r_en, cigar_str, blen, mlen

CIGAR operations: 0=M (match), 1=I (insertion), 2=D (deletion), 3=N (skip), 4=S (soft-clip), 5=H (hard-clip)

PairedAlignment contains: read1, read2 (Alignment objects), is_proper_pair (bool), insert_size (int or None)

License

Python bindings: Mozilla Public License 2.0
BWA: GNU General Public License v3.0

Metadata

Release files for bwamem 0.0.56

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bwamem 0.0.56
File	Size	Uploaded	Provenance
bwamem-0.0.56.tar.gz	1.1 MB	Aug 22, 2026	With provenance	Details

Built distributions (wheels)

Table of built distributions (wheels) for bwamem 0.0.56
File	Interpreter	ABI	Platform	Reset
bwamem-0.0.56-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 386.1 kB Aug 22, 2026 With provenance	CPython 3.13	CPython 3.13	Linux glibc 2.17+ x86-64	Details
bwamem-0.0.56-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 386.1 kB Aug 22, 2026 With provenance	CPython 3.12	CPython 3.12	Linux glibc 2.17+ x86-64	Details

Total release size: 1.9 MB

Release files / bwamem-0.0.56.tar.gz

Download URL	bwamem-0.0.56.tar.gz
Size	1.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`e73498615f5a0745758e102dda8e8de72fc415bc19d5c7b5c00b9f3f12f70c22`
BLAKE2b-256 checksum How to use checksums	`c0a326adf28f4a193d233357940c1709f06beb477b0efd6431bc5e2574f8e583`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/y9c/bwamem
Publishing commit: github.com/y9c/bwamem/tree/81994fd9858b190fe24965f61ab8db882b858147

Workflow

Publishing configuration: github.com/y9c/bwamem/blob/81994fd9858b190fe24965f61ab8db882b858147/.github/workflows/publish.yml
Publishing logs: github.com/y9c/bwamem/actions/runs/32593835537/attempts/1

Artifact

Subject: bwamem-0.0.56.tar.gz
SHA-256 checksum: e73498615f5a0745758e102dda8e8de72fc415bc19d5c7b5c00b9f3f12f70c22 Verifying attestations

Release files / bwamem-0.0.56-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	bwamem-0.0.56-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	386.1 kB
Tags	CPython 3.13 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`ac6e777cc40ae9a3581e8e53e5a483c3af01d92ead66352996fd0027a71f64ec`
BLAKE2b-256 checksum How to use checksums	`f5b60ab28931781cd49e1c770a730a2def0b2f80e9380e87962407965ed3dc06`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/y9c/bwamem
Publishing commit: github.com/y9c/bwamem/tree/81994fd9858b190fe24965f61ab8db882b858147

Workflow

Publishing configuration: github.com/y9c/bwamem/blob/81994fd9858b190fe24965f61ab8db882b858147/.github/workflows/publish.yml
Publishing logs: github.com/y9c/bwamem/actions/runs/32593835537/attempts/1

Artifact

Subject: bwamem-0.0.56-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
SHA-256 checksum: ac6e777cc40ae9a3581e8e53e5a483c3af01d92ead66352996fd0027a71f64ec Verifying attestations

Release files / bwamem-0.0.56-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	bwamem-0.0.56-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	386.1 kB
Tags	CPython 3.12 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`2a6a017c2ff95877d339d9a51d4b6f97d58074fd13a2ddee8483e516a07629ab`
BLAKE2b-256 checksum How to use checksums	`95d98647f3c7a37fe8f34f3068ad800470022805521a5fa7a9c47cf653010d9f`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/y9c/bwamem
Publishing commit: github.com/y9c/bwamem/tree/81994fd9858b190fe24965f61ab8db882b858147

Workflow

Publishing configuration: github.com/y9c/bwamem/blob/81994fd9858b190fe24965f61ab8db882b858147/.github/workflows/publish.yml
Publishing logs: github.com/y9c/bwamem/actions/runs/32593835537/attempts/1

Artifact

Subject: bwamem-0.0.56-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
SHA-256 checksum: 2a6a017c2ff95877d339d9a51d4b6f97d58074fd13a2ddee8483e516a07629ab Verifying attestations

Security for bwamem 0.0.56

Report project as malware

Provenance

Full provenance

All 3 files in this release have been uploaded with provenance metadata.

Attestation for bwamem-0.0.56.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/y9c/bwamem
Publishing commit: github.com/y9c/bwamem/tree/81994fd9858b190fe24965f61ab8db882b858147

Workflow

Publishing configuration: github.com/y9c/bwamem/blob/81994fd9858b190fe24965f61ab8db882b858147/.github/workflows/publish.yml
Publishing logs: github.com/y9c/bwamem/actions/runs/32593835537/attempts/1

Artifact

Subject: bwamem-0.0.56.tar.gz
SHA-256 checksum: e73498615f5a0745758e102dda8e8de72fc415bc19d5c7b5c00b9f3f12f70c22 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.