samtools-head(1)

✨ samtools-head(1) ✨

ok so this is the samtools head page, straight out of the Bioinformatics tools manual set — like, the whole samtools manual family, and this is the little head one 🎀

---

🌸 NAME 🌸

samtools head — peek at the headers of a SAM/BAM/CRAM file, bestie 👑

---

🦋 SYNOPSIS 🦋

samtools head [-h INT] [-n INT] [FILE]

---

💖 DESCRIPTION 💖

so like, by default? it prints all the headers from the input file you gave it, out to standard output, in SAM format. slay. ✨

the input alignment file can be SAM, BAM, or CRAM — all three are valid, no cap. and if you don't give it a FILE at all? it just reads from standard input. easy. 🫶

if you use the right options, you can get just some of the headers and/or, bonus, some of the alignment records too. iconic behaviour honestly.

here's the thing though, and this is important: samtools head outputs SAM headers exactly as they appear in the input file. like, character for character, it does not touch them. in particular — and this is the part people miss — it never adds an @PG header itself. ever. 🙈

and like, why does that matter? because other samtools commands do add those @PG headers, specifically to help with provenance tracking in analysis pipelines. but samtools head never outputs more than a handful of alignment records, so it's honestly unsuitable for that kind of pipeline context anyway. so it just… doesn't. periodt. 💅

---

💅 OPTIONS 💅

• -h, --headers INT — only show the first INT header lines. by default, all header lines get displayed 🌈
• -n, --records INT — also show the first INT alignment records. by default, zero alignment records are displayed — none, nada 🍓

---

👑 AUTHOR 👑

written by John Marshall from the University of Glasgow. we stan 💜

---

🔥 SEE ALSO 🔥

• samtools(1)
• samtools-view(1)

---

ok that's the whole page bestie, go read some headers 💖✨

samtools-1.24 · 9 July 2026 — mwah, that's a wrap, this was samtools-head(1) and she ate 🎀🦋