Migration to Pysam 0.24

Use this checklist when moving an existing environment or pipeline to pysam 0.24.0.

Runtime Baseline

Pysam 0.24.0 was released 27 April 2026.
It was tested with Python 3.8–3.14.
It wraps HTSlib/samtools/bcftools 1.23.1.
It requires Cython 3 when building/extending from source.
The release notes expect 0.24 to be the final line supporting Python 3.8.

For a reproducible environment:

uv pip install "pysam==0.24.0"

If maintaining Python/Cython extensions that cimport pysam declarations, rebuild them against 0.24. Do not reuse binaries built against a different pysam ABI without verification.

CRAM Behavior

Output version

New CRAM output defaults to CRAM 3.1. If downstream software only supports 3.0:

pysam.AlignmentFile(
    "output.cram",
    "wc",
    header=header,
    reference_filename="reference.fa",
    format_options=["version=3.0"],
)

Upgrade downstream tooling instead of forcing 3.0 when possible.

Reference lookup

Implicit EBI reference fetching is no longer enabled by default. Existing pipelines that relied on hidden network retrieval can now fail.

Preferred fix:

pysam.AlignmentFile(
    "input.cram",
    "rc",
    reference_filename="reference.fa",
)

Only configure REF_PATH and REF_CACHE when managed checksum-based lookup is intentional. Do not restore remote fetching without documenting network, cache, and provenance behavior.

`format_options`

Pysam 0.24 fixes Python 3 handling so AlignmentFile(format_options=...) and HTSFile.add_hts_options() accept documented str values rather than requiring bytes:

format_options=["version=3.0"]

Remove workarounds that encode these strings to bytes.

CIGAR Constants

Pysam 0.23.2 restored top-level aliases such as pysam.CMATCH after a Cython behavior change, but the release notes warn that a future release will remove them.

Migrate new and maintained code:

# Compatibility alias
pysam.CMATCH

# Preferred
pysam.CIGAR_OPS.CMATCH

Audit all CIGAR operators, not only CMATCH.

Modified Bases

Pysam 0.24:

removes the prior five-modification-type limit in AlignedSegment.modified_bases
fixes a crash for degenerate MM fields that describe no modified bases

Retest MM/ML parsing with:

multiple modification codes
empty/degenerate MM tags
missing ML tags
forward and reverse alignments
modified_bases_forward

Quality Conversion

pysam.array_to_qualitystring() was optimized substantially in 0.24. Remove custom micro-optimizations only after confirming identical handling of missing or invalid values.

Coverage and Python 3.13+

The 0.24 release fixes coverage functionality for Python 3.13 and later. Re-run count_coverage() regression cases when upgrading both Python and pysam:

zero-depth positions
base-quality threshold boundaries
duplicate/secondary/supplementary filtering
ambiguous query bases
contig boundaries

Variant Documentation and Errors

Pysam 0.24 adds documentation for many VariantHeader and VariantRecord internal field wrappers. Prefer documented public mappings and methods over introspection into Cython implementation details.

Recent 0.23.x releases also improved AlignmentFile and VariantFile I/O exception handling. Catch specific OSError/ValueError conditions and do not depend on old message text.

Avoid Pysam 0.23.1 for Cython Extensions

Pysam 0.23.1 was yanked because it broke binary compatibility for Cython projects by changing AlignedSegment size. Pysam 0.23.2 restored compatibility. Pure Python users were not affected in the same way.

When migrating from 0.23:

skip 0.23.1
rebuild extension modules
test Cython cimports against the 0.24 declarations

Dispatcher Output

Keep wrapped command output out of memory for bulk or binary operations:

import pysam.samtools

pysam.samtools.sort(
    "-o",
    "sorted.bam",
    "input.bam",
    catch_stdout=False,
)

This is not new to 0.24, but it is important when updating older examples that omit catch_stdout=False.

Regression Checklist

Print and record pysam.__version__ and pysam.__samtools_version__.
Open representative BAM, CRAM, VCF.gz, BCF, FASTA, FASTQ, and tabix files.
Compare numeric queries with equivalent region strings.
Decode CRAM with no network and an explicit reference.
Write/read CRAM 3.1; test 3.0 only if required.
Rebuild all Cython extensions.
Exercise pileup and count_coverage() thresholds.
Test modified-base MM/ML edge cases.
Run sort/index/normalization dispatchers with file output.
Recreate indexes and compare known regions and aggregate counts.