Tips and best practices

Quick operational pointers for running bwa-mem3. Each links to the page with the full rationale.

• Index once, align many. The on-disk index is stable across bwa-mem3 releases and across every SIMD tier in the binary; you do not re-index when upgrading unless the release notes say so. See Indexing the reference.

• Pipe --bam straight into samtools sort — never write an intermediate unsorted BAM. See Best Practices → Output format.

• Stage the index in shared memory for batch workloads (bwa-mem3 shm), and always shm -d before re-indexing — there is no staleness check. See Quick start: shared-memory index and Anti-patterns.

• Divide threads explicitly across concurrent jobs so the total stays at or below the physical core count. See Threading and resource use.

• Confirm the resolved SIMD tier with bwa-mem3 version (or BWAMEM3_DEBUG_SIMD=1); one binary carries every tier and selects at startup. See Performance → SIMD dispatch matrix.

• Always pass a read-group (-R with at least ID: and SM:) — GATK, fgbio, and Picard require an @RG header. See Aligning short reads.

For an impact-ordered tuning walkthrough, see Best Practices → Optimization checklist.

See also: Aligning short reads (mem) · Threading and resource use · Best Practices: optimization checklist · Best Practices: anti-patterns