How to View a BAM File

If you want to look at a BAM file, use two tools. samtools view and samtools tview for anything you can express as a region or a filter, and IGV (Integrative Genomics Viewer) for the cases where you need to see the reads stacked against the reference. Everything else on the market is a variation on one of those two modes. A BAM file is a BGZF-compressed binary encoding of SAM alignment records, so you cannot cat it, but you can stream any region of it in milliseconds once it has a .bai index.

This page covers the mechanics. You will see how to get the index, the samtools commands worth memorizing, and how to configure IGV so it tells you something useful. It also covers the specific artifacts you should look for before believing a variant.

Get the index first, then stop worrying about file size

A 30x whole-genome BAM is 60 to 100 GB. A CRAM of the same data is roughly 40 to 60 percent of that, because CRAM stores bases by reference difference rather than literally. Neither size matters for viewing, because BAM and CRAM are both block-compressed and coordinate-sorted, and a companion index lets a reader seek straight to the block containing a given chromosome position.

samtools index -@ 8 sample.bam        # writes sample.bam.bai
samtools quickcheck -v sample.bam     # confirms EOF block and headers

If samtools index fails with “the input is not sorted”, your BAM is in name order or unsorted. Fix it with samtools sort -@ 8 -m 2G -o sorted.bam sample.bam and index that. For CRAM you also need the exact reference FASTA the file was aligned to, passed as -T GRCh38.fa. Get the wrong reference build and the bases decode to garbage that looks superficially plausible, which is the most annoying failure mode in this whole area.

Check which build you have before anything else:

samtools view -H sample.bam | grep '^@SQ' | head -3

GRCh38 has chr1 at length 248956422. GRCh37/hg19 has 1 at 249250621. That single number tells you which coordinate system every position in the file refers to.

The samtools commands that answer most questions

Most of the time you do not want a picture. You want to know what the reads say at one position, and a text view is faster and easier to script.

To see raw records in a region as tab-delimited SAM text:

samtools view sample.bam chr7:117559590-117559620

To see them as a pileup against the reference, which is closer to what a graphical viewer shows:

samtools tview -p chr7:117559590 -d T sample.bam GRCh38.fa

-d T dumps a text rendering to stdout instead of opening the curses interface, which makes it pipeable. In the interactive mode, . and , mark reads matching the reference on the forward and reverse strands. Mismatched bases print as letters.

For allele counts at a single site, which is usually the real question:

samtools mpileup -f GRCh38.fa -r chr7:117559590-117559590 -q 20 -Q 20 sample.bam

-q 20 drops reads with mapping quality below 20, and -Q 20 drops individual bases with quality below 20. Both defaults are looser than you want. A site that looks heterozygous with no filters and homozygous reference at MAPQ 20 is telling you the alternate reads are multi-mapping, which usually means a segmental duplication or a pseudogene.

Two more worth having in your shell history. samtools flagstat sample.bam gives total reads, duplicate rate, and properly paired percentage in a few seconds from the index statistics. samtools coverage -r chr7:117000000-118000000 sample.bam gives mean depth and the fraction of the region covered at all.

If you are building anything programmatic on top of BAM, the underlying APIs are stable and well documented. BamTools exposes a C++ interface plus a command-line toolkit for merging, filtering, and converting.¹ In Python, pysam wraps htslib and gives you an iterator over AlignedSegment objects with per-read access to CIGAR strings and tags.

IGV is the viewer to use, with these settings changed

IGV is the standard desktop viewer and the one whose rendering conventions everyone else copies. Load your reference genome first, then the BAM. IGV needs the .bai next to the .bam and will refuse to load otherwise. It will not render anything until you zoom below roughly 30 kb of visible span, which is a deliberate limit on how many reads it will pull into memory.

Four changes to the defaults make it substantially more informative. Turn on “Shade base by quality” so low-confidence mismatches appear faint. Enable “Show soft-clipped bases”, because clipped sequence at a consistent position is often the only visible signature of a structural breakpoint. Set “Color alignments by” to “insert size and pair orientation”, which makes deletions and inversions show up as red and blue read pairs. Finally, group by “base at position” when you are looking at one variant, which separates reference and alternate reads into two visual blocks.

Hovering a read gives you its MAPQ, CIGAR string, and tags. A MAPQ of 0 from BWA-MEM means the read maps equally well somewhere else. In a stack where most reads are MAPQ 0, no variant call is trustworthy regardless of depth.

When a lighter viewer makes sense

IGV is a desktop Java application, which is wrong for two situations: rendering thousands of loci in a batch, and embedding a view in a web report. Several tools exist for precisely this gap. BamSnap generates static read-pile images from BAM files and is designed to be fast enough for large-scale automated review.² Alview is a portable single-binary viewer aimed at inspecting specific reads without a heavy installation.³ Bambino combines a Java alignment viewer with a variant detector in one application.⁴

For long reads, the calculus changes. Nanopore and PacBio reads carry structural variation within single reads, so the informative picture is the CIGAR string of one read rather than a pileup of many. SVhawkeye is built for this and renders targeted structural fragments directly from BAM.⁵

Two tools deserve a note as history. BamView was an interactive Java viewer from Sanger that introduced several conventions still in use.⁶ It was extended for paired-read and multi-BAM views in later work.⁷ It was archived in 2022, so do not start a new workflow on it. GBrowse 2.0 served the browser-track use case and can render alignment data alongside annotation.⁸

If your question is coverage rather than individual reads, skip viewers entirely and make a track. BAMscale computes scaled coverage from BAM and writes bigWig output suitable for any genome browser.⁹

What to look for before you trust what you see

A pileup is evidence. It is not a conclusion. Five patterns explain most false positives, and all five are visible by eye.

Strand bias comes first. If every alternate read is on the forward strand and coverage is balanced, you are probably looking at a sequencing or alignment artifact rather than a real allele. Position bias is second. Alternate bases clustered in the last few cycles of every read reflect quality decay at read ends.

Third, check the local context. Variants inside homopolymers of six or more identical bases, or inside short tandem repeats, are the hardest class to call correctly. Different aligners will place the same indel at different positions. Fourth, look at the duplicate flag. IGV hides duplicates by default, and a variant supported mostly by duplicate reads comes from one original fragment. Fifth, note soft clips. A cluster of reads all clipping at the same coordinate usually means the true sequence differs structurally from the reference there.

One more point that matters more than any of the above. A BAM view tells you what the sequencer read and where the aligner put it. It says nothing about what a variant means for you. Interpreting a variant in a clinical context, including anything you would act on, requires a clinician and confirmation in an accredited laboratory. Research-grade BAM files are for understanding your own data, and we think that is a good reason to look at them.

Questions people also ask

How do I convert a BAM to a readable text file? Run samtools view -h sample.bam > sample.sam for the whole file, or add a region like chr1:1000-2000 to extract just that slice. A full WGS SAM is on the order of 400 GB of text, so always restrict by region unless you are piping into something.

Can I view a BAM file without downloading it? Yes, if it is served over HTTP with range request support and the .bai sits beside it. Both samtools and IGV accept a URL in place of a path and will fetch only the compressed blocks covering your region, which is typically a few megabytes.

Why does IGV show nothing when I load my BAM? Three usual causes: you are zoomed out past the visibility threshold, the chromosome naming does not match your reference (chr1 against 1), or the index is missing or stale. Regenerate the index and check the @SQ lines in the header against the genome you loaded.

What is the difference between BAM and CRAM for viewing? CRAM stores bases relative to a reference, so it is smaller but requires the exact original reference FASTA to decode. Viewing is otherwise identical, and samtools view -T ref.fa handles CRAM everywhere BAM works.

Is there a good browser-based BAM viewer? bam.iobio runs in the browser and gives fast summary statistics from a local or remote file without a full upload. It is good for a quality overview and not a substitute for read-level inspection.

Footnotes

1. Derek W. Barnett, Erik K. Garrison, Aaron R. Quinlan, et al. BamTools: a C++ API and toolkit for analyzing and managing BAM files. Bioinformatics, 2011. https://doi.org/10.1093/bioinformatics/btr174 ↩

2. Minseok Kwon, Soohyun Lee, Michele Berselli, et al. BamSnap: a lightweight viewer for sequencing reads in BAM files. Bioinformatics, 2021. https://doi.org/10.1093/bioinformatics/btaa1101 ↩

3. Richard P. Finney, Qing-Rong Chen, Cu V. Nguyen, et al. Alview: Portable Software for Viewing Sequence Reads in BAM Formatted Files. Cancer Informatics, 2015. https://doi.org/10.4137/cin.s26470 ↩

4. Michael N. Edmonson, Jinghui Zhang, Chunhua Yan, et al. Bambino: a variant detector and alignment viewer for next-generation sequencing data in the SAM/BAM format. Bioinformatics, 2011. https://doi.org/10.1093/bioinformatics/btr032 ↩

5. Yuhui Xiao, Tao Yu, Fan Liang, et al. SVhawkeye: an ultra-fast software for user-friendly visualization of targeted structural fragments from BAM files. Frontiers in Genetics, 2024. https://doi.org/10.3389/fgene.2024.1352443 ↩

6. Tim Carver, Ulrike Böhme, Thomas D. Otto, et al. BamView: viewing mapped read alignment data in the context of the reference sequence. Bioinformatics, 2010. https://doi.org/10.1093/bioinformatics/btq010 ↩

7. T. Carver, S. R. Harris, T. D. Otto, et al. BamView: visualizing and interpretation of next-generation sequencing read alignments. Briefings in Bioinformatics, 2012. https://doi.org/10.1093/bib/bbr073 ↩

8. L. D. Stein. Using GBrowse 2.0 to visualize and share next-generation sequence data. Briefings in Bioinformatics, 2013. https://doi.org/10.1093/bib/bbt001 ↩

9. Lorinc S. Pongor, Jacob M. Gross, Roberto Vera Alvarez, et al. BAMscale: quantification of next-generation sequencing peaks and generation of scaled coverage tracks. Epigenetics & Chromatin, 2020. https://doi.org/10.1186/s13072-020-00343-x ↩