{"library":"pysam","title":"PySAM","description":"Pysam is a Python module for reading, manipulating, and writing genomic datasets. It is a lightweight wrapper of the HTSlib API, providing facilities to work with SAM/BAM/CRAM, VCF/BCF, BED, GFF/GTF, FASTA/FASTQ files, and access samtools/bcftools command-line functionality. The module supports compression and random access through indexing. Pysam is actively maintained with regular releases, often wrapping new versions of the underlying htslib, samtools, and bcftools C libraries.","language":"python","status":"active","last_verified":"Thu May 14","install":{"commands":["pip install pysam"],"cli":null},"imports":["import pysam","from pysam import AlignmentFile","from pysam import VariantFile","from pysam import FastaFile"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import pysam\nimport os\n\n# --- Example 1: Read a BAM/SAM file ---\n# Create a dummy BAM file for demonstration\n# In a real scenario, you would use an existing BAM file and its index.\n# For this quickstart, we'll create a simple unmapped SAM file first.\n# NOTE: pysam.AlignmentFile requires a header for 'wb' mode.\n\nheader = {\n    'HD': {'VN': '1.0'},\n    'SQ': [{'LN': 1000, 'SN': 'chr1'}]\n}\n\ndummy_sam_path = \"example_reads.sam\"\nwith pysam.AlignmentFile(dummy_sam_path, \"wh\", header=header) as outfile:\n    # Create a simple unmapped read (no reference_id or pos)\n    read = pysam.AlignedSegment(header)\n    read.query_name = \"read1\"\n    read.query_sequence = \"ATGCATGC\"\n    read.query_qualities = pysam.qualities_to_ints(\"BBBBBBBB\")\n    read.flag = 4 # UNMAPPED\n    outfile.write(read)\n\nprint(f\"Reading from {dummy_sam_path}:\")\nwith pysam.AlignmentFile(dummy_sam_path, \"r\") as samfile:\n    for read in samfile.fetch(until_eof=True): # fetch(until_eof=True) for unindexed or SAM files\n        print(f\"  Read: {read.query_name}, Sequence: {read.query_sequence}, Mapped: {not read.is_unmapped}\")\nos.remove(dummy_sam_path)\n\n# --- Example 2: Read a VCF file ---\n# Create a dummy VCF file\ndummy_vcf_path = \"example_variants.vcf\"\nwith open(dummy_vcf_path, \"w\") as f:\n    f.write(\"##fileformat=VCFv4.2\\n\")\n    f.write(\"##contig=<ID=chr1,length=1000>\\n\")\n    f.write(\"#CHROM\\tPOS\\tID\\tREF\\tALT\\tQUAL\\tFILTER\\tINFO\\tFORMAT\\tSAMPLE1\\n\")\n    f.write(\"chr1\\t100\\t.\\tA\\tG\\t100\\tPASS\\t.\\tGT\\t0/1\\n\")\n    f.write(\"chr1\\t200\\t.\\tC\\tT\\t90\\tPASS\\t.\\tGT\\t1/1\\n\")\n\nprint(f\"\\nReading from {dummy_vcf_path}:\")\nvcf_file = pysam.VariantFile(dummy_vcf_path, \"r\")\nfor variant in vcf_file:\n    print(f\"  Variant: {variant.chrom}:{variant.pos} {variant.ref}>{variant.alts}\")\nvcf_file.close()\nos.remove(dummy_vcf_path)\n\n# --- Example 3: Read a FASTA file ---\n# Create a dummy FASTA file\ndummy_fasta_path = \"example_reference.fasta\"\nwith open(dummy_fasta_path, \"w\") as f:\n    f.write(\">chr1\\n\")\n    f.write(\"ATGCATGCATGCATGCATGCATGCATGCATGCATGCATGC\\n\")\n    f.write(\">chr2\\n\")\n    f.write(\"GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG\\n\")\n\nprint(f\"\\nReading from {dummy_fasta_path}:\")\nfasta_file = pysam.FastaFile(dummy_fasta_path)\nsequence = fasta_file.fetch(\"chr1\", 5, 15) # 0-based start, 0-based exclusive end\nprint(f\"  Fetched sequence from chr1 (5-15): {sequence}\")\nfasta_file.close()\nos.remove(dummy_fasta_path)","lang":"python","description":"This quickstart demonstrates how to open and read data from common genomic file formats (SAM, VCF, FASTA) using `pysam.AlignmentFile`, `pysam.VariantFile`, and `pysam.FastaFile`. It includes creating dummy files for a self-contained example.","tag":null,"tag_description":null,"last_tested":"2026-04-25","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]},"compatibility":{"tag":null,"tag_description":null,"last_tested":"2026-05-14","installed_version":"0.24.0","pypi_latest":"0.24.0","is_stale":false,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":2.3,"avg_import_s":0.08,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.06,"mem_mb":2.8,"disk_size":"76.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.8,"disk_size":"77.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.2,"import_time_s":0.05,"mem_mb":2.8,"disk_size":"90M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":2.8,"disk_size":"93M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.08,"mem_mb":2.8,"disk_size":"99.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.1,"disk_size":"101.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.3,"import_time_s":0.1,"mem_mb":2.8,"disk_size":"114M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.1,"disk_size":"118M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.07,"mem_mb":2.9,"disk_size":"71.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.1,"disk_size":"73.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.1,"import_time_s":0.15,"mem_mb":2.9,"disk_size":"86M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.2,"disk_size":"90M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.06,"mem_mb":2.9,"disk_size":"91.0M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.2,"disk_size":"95.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.1,"import_time_s":0.08,"mem_mb":2.8,"disk_size":"105M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":3,"disk_size":"113M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"95.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.8,"disk_size":"97.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.9,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"109M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pysam","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.8,"disk_size":"113M"}]}}