---

name: troubleshooting-build description: "Guides agents troubleshooting pysam installation, source builds, imports, Cython extension linking, htslib selection, typing stubs, deprecated names, and platform build failures." disable-model-invocation: true metadata: disco-role: operating license: MIT

troubleshooting-build

Use this sub-skill when a task involves installing or importing pysam, diagnosing wheel/source build failures, choosing builtin versus external htslib, compiling Cython code against pysam, resolving runtime linker errors, migrating old extension-module names, or understanding typing/deprecation caveats.

Read first

• references/install-build-reference.md for Bioconda, PyPI wheels, source builds, builtin/external htslib, environment variables, profiling, and platform caveats.
• references/extension-development.md for get_include(), get_libraries(), get_defines(), Cython cimport patterns, lib* extension module names, and type stub expectations.
• references/troubleshooting.md for common failure signatures and targeted fixes.
• scripts/inspect_build_config.py for a safe JSON probe of a local pysam install. It redacts local paths by default; use --show-paths only when the user explicitly wants machine-specific diagnostics.

Scope

This sub-skill owns installation, import, build, link, and extension-development issues for pysam 0.24.x and its wrapped htslib, samtools, and bcftools versions.

Use sibling sub-skills instead for data workflows after pysam imports successfully:

• ../alignment-io/SKILL.md for AlignmentFile, AlignedSegment, SAM/BAM/CRAM, pileup, indexes, and coordinate behavior.
• ../variant-io/SKILL.md for VariantFile, headers, VCF/BCF records, sample subsetting, and record translation.
• ../tabix-fasta/SKILL.md for tabix-indexed tables, TabixFile, FastaFile, BGZF/index helpers, and FASTA access.
• ../command-wrappers/SKILL.md for pysam.samtools, pysam.bcftools, top-level command aliases, and SamtoolsError handling.

Defaults that prevent common mistakes

• Prefer Bioconda when the user needs the least fragile install path or wants non-Python dependencies resolved automatically.
• Prefer normal pip install pysam only when a compatible wheel exists or the environment has a working compiler toolchain and htslib build dependencies.
• For repository installs, ensure Cython is installed first; PyPI source distributions can include generated C files, but repository checkouts require Cython.
• Treat HTSLIB_LIBRARY_DIR and HTSLIB_INCLUDE_DIR as a matched pair for external htslib, and verify runtime linking with the dynamic loader path if libhts cannot be found.
• Use pysam.get_include(), pysam.get_libraries(), and pysam.get_defines() when compiling Cython extensions that link against pysam internals.
• Migrate old direct extension imports such as pysam.csamtools to pysam.libcsamtools; direct extension modules use the lib prefix in modern pysam.