Developer’s guide

Code organization

The top level directory is organized in the following directories:


Code specific to pysam.


The documentation. To build the latest documentation, first install Sphinx and then type:

make -C doc html

Code and data for testing and benchmarking.


Source code from htslib shipped with pysam. See about importing.


Source code from samtools shipped with pysam. See about importing.


Source code from bcftools shipped with pysam. See about importing.

Importing new versions of htslib and samtools

See instructions in to import the latest versions of htslib, samtools and bcftools.

Unit testing

Unit tests are in the tests directory. To run all unit tests, run:

pytest tests

Most tests use test data from the tests/*_data directories. Some of these test data files are generated from other files in these directories, which is done by running make in each directory:

make -C tests/pysam_data
# etc

Alternatively if any tests/*_data/all.stamp file is not already present, running the unit tests should generate that directory’s data files automatically.


To run the benchmarking suite, make sure that pytest-benchmark is installed. To run all benchmarks, type:

pytest tests/*

See Benchmarking for more on this topic.


Please see Github for a list of all contributors:

Many thanks to all contributors for helping in making pysam useful.