samtools-tview(1)

💅 samtools-tview 💅

ok so real talk, this is the samtools tview page from the samtools manual — the cute little interactive alignment viewer — and i'm gonna walk you through every single bit of it, no skips, no "you'll figure it out" energy 💖

---

✨ NAME ✨

samtools tview — display alignments in a curses-based interactive viewer 🦋

like, yes bestie, your BAM alignments. in a terminal. with ncurses. iconic behavior honestly.

---

🌸 SYNOPSIS 🌸

samtools tview [-p chr:pos] [-s STR] [-d display] in.sorted.bam
[ref.fasta]

that's the whole vibe. sorted bam in, optional reference fasta, some flags if you're feeling spicy 🔥

---

🎀 DESCRIPTION 🎀

so this is the text alignment viewer — it's based on the ncurses library, meaning it runs right there in your terminal and it's fully interactive. main character energy fr 💅

once you're inside the viewer:

• hit ? for help — yes it has a help menu, she's helpful
• hit g to jump the alignment start to a region. the format is like chr10:10,000,000, or =10,000,000 when you're viewing the same reference sequence as before ✨

now, the layout, top to bottom:

1. the top line shows the reference sequence — or just a bunch of 'N's if the reference is unknown 🫠
2. underneath that is the consensus, derived from the sequence alignments
3. below the consensus, all the sequence alignment records get shown

and about the casing: uppercase vs lowercase is how you tell the sequence strand apart. uppercase = top / forward strand, periodt 👑

when the reference is known, both the consensus and the alignment record sequences get displayed in a dot-notation 🎀 where a matching character shows up as '.' (forward strand) or ',' (reverse strand), and like... only the mismatching bases and the missing bases actually show up as letters. sneak peek just the drama, love that for us.

you can toggle this mode on and off with the "." command 💫

---

⭐ OPTIONS ⭐

• -d display — output as (H)tml, (C)urses or (T)ext. that's the display mode bestie, pick your fighter.

the width of the generated text is controlled by the COLUMNS environment variable, or by the -w option for the non-curses outputs 👀 heads up tho: COLUMNS may be a local shell variable, so you might need to export it first, or just specify it right on the command line before the command. like so:

export COLUMNS ; samtools tview -d T -p 1:234567 in.bam

• -p chr:pos — go directly to this position 🚀 no scrolling around like a lost little guy.
• -s STR — display only alignments from this sample or read group. STR has to match either an ID or SM field in an @RG header record, no cap. for example:

samtools tview -p chr20:10M -s NA12878 grch38.fa

• -w INT — specifies the display width when using the HTML or Text output modes 📏 (curses does its own thing, she doesn't need it).
• -X — if this option is set, it will allows user to specify customized index file location(s) if the data folder does not contain any index file 🗂️ (yes i kept the original wording, she said "it will allows", we respect her). example usage:

samtools tview [options] -X </data_folder/data.bam>
[/index_folder/index.bai] [ref.fasta]

lowkey important: in.sorted.bam in the synopsis — the bam's gotta be sorted. the manpage says it, i'm saying it, we're all saying it together 🫶

---

👑 AUTHOR 👑

written by Heng Li from the Sanger Institute 💜 an absolute legend, we stan.

---

🌈 SEE ALSO 🌈

• samtools(1)
• Samtools website: <http://www.htslib.org/>

---

and that's the whole page bestie, every flag accounted for, nothing dropped, we ate and left no crumbs 🍓

samtools-1.24 · 9 July 2026 — that's the version and date this page shipped with, mwah 💋 catch you in the next manpage 😭💖