samtools-split(1)

💅 samtools-split(1) — bestie edition 🎀

ok so this is a page from the Bioinformatics tools manual set, and the star of the show is samtools split. buckle up, it's actually such a clean little tool 🦋

---

✨ NAME ✨

samtools split — it splits a file by read group. that's it, that's the vibe 💫

---

🌸 SYNOPSIS 🌸

samtools split [options] merged.sam|merged.bam|merged.cram

---

👑 DESCRIPTION 👑

so the whole thing splits a file by read group (or by a tag you pick), and it produces one or more output files that all match a common prefix — and by default that prefix is based on the input filename. cute, right? 🎀

unless you use the -d option, the file gets split according to the @RG tags listed in the header. and listen — records with no RG tag, or with an RG tag that's undefined in the header, will make the program exit with an error 😭 unless you use the -u option. no cap.

RG values defined in the header but with no records? they still produce an output file that only contains a header. main character energy tbh 👑

if you use the -d TAG option, the file gets split on the value in the given aux tag instead. only string (type Z) and integer (type i in SAM, plus the equivalents in BAM/CRAM) tags are currently supported — that's the limit, bestie. and unless you use -u, the program exits with an error if it finds a record without the given tag 💀

⚠️ heads up: splitting on a tag with high cardinality can literally create a huge number of output files. to prevent that whole situation, use the -M option to set a limit on the number of splits made. protecting you from yourself, iconic behavior 🫶

using -d RG behaves in a similar way to the default (i.e. without -d) — it opens an output file for each @RG line in the header. but unlike the default, new output files will be opened for any RG tags found in the alignment records irrespective of whether they have a matching header @RG line. wild, I know ✨

the -u option lets you specify the output filename for any records with a missing or unrecognised tag. and this option will always write out a file, even if there are no records. always. periodt 💅

output format defaults to BAM. so for SAM or CRAM, either set the format with --output-fmt or use -f to set the file extension, like -f %*_%#.sam. easy 🌈

---

💖 OPTIONS 💖

• -u FILE1 — put reads with no tag or an unrecognised tag into FILE1 🙈
• -h FILE2 — use the header from FILE2 when writing the file given in the -u option. this header completely replaces the one from the input file 😳 it must be compatible with the input file header, which means it must have the same number of references listed in the @SQ lines, and the references must be in the same order and have the same lengths. no mixing and matching, bestie.
• -f STRING — output filename format string (see the expansions below) — default is "%*_%#.%." ⭐
• -d TAG — split reads by TAG value into distinct files. only the TAG key has to be supplied with the option. the value of the TAG has to be a string (i.e. key:Z:value) or an integer (key:i:value) 🌸

using this option changes the default filename format string to "%*_%!.%", so that tag values appear in the output file names. and yes, you can override that with the -f option 👑

• -p NUMBER — pad numeric values in %# and %! format expansions to this many digits using leading zeros. for %!, only integer tag values get padded — string tag values are left unchanged, even if the value only includes digits. rude but fair 💀
• -M, --max-split NUM — limit the number of files created by the -d option to NUM (default 100). this prevents accidents where trying to split on a tag with high cardinality could result in the creation of a very large number of output files 😭 once the file limit is reached, any tag values not already seen will be treated as unmatched, and the program will exit with an error unless the -u option is in use.

if desired, the limit can be removed using -M -1 — although in practice the number of outputs will still be restricted by system limits on the number of files that can be open at once. so like, you can try 🫶

if splitting by read group, and the read group count in the header is higher than the requested limit, then the limit will be raised to match. it's very accommodating like that ✨

• -v — verbose output. she talks more 📣
• --no-PG — do not add a @PG line to the header of the output file 🙅‍♀️
• Format string expansions: these are the little magic bits you can drop into your filename format 💫
  • %% — %
  • %* — basename
  • %# — index (of @RG in the header, or count of TAG values seen so far)
  • %! — @RG ID or TAG value
  • %. — output format filename extension
• -@, --threads INT — number of input/output compression threads to use in addition to the main thread. default is [0] 🧚

---

⭐ AUTHOR ⭐

written by Martin Pollard from the Sanger Institute. legend behavior, honestly 👏

---

🦋 SEE ALSO 🦋

samtools(1), samtools-addreplacerg(1)

Samtools website: <http://www.htslib.org/> — go poke around, it's giving resources 💜

---

and that's the whole page, bestie!! this was samtools-split(1) from samtools-1.24, dated 9 July 2026 — screenshot it, cite it, love it 💖🎀✨