samtools-merge(1)

💅 samtools-merge — the samtools merge page, bestie edition 🎀

okay so you're looking at samtools-merge(1), one of the cool kids in the Bioinformatics tools corner of the samtools fam. pull up a chair, this one's actually so good 🦋

---

✨ NAME ✨

samtools merge — merges multiple sorted files into a single file. that's it. that's the whole vibe. 💫

---

🌸 SYNOPSIS 🌸

samtools merge [options] -o out.bam [options] in1.bam ... inN.bam

samtools merge [options] out.bam in1.bam ... inN.bam

two ways to serve the same look, pick your fighter 💅

---

💖 DESCRIPTION 💖

So what this does: it merges multiple sorted alignment files and produces one sorted output file that contains, like, all the input records and keeps the existing sort order. no cap, all of it, in order. 🔥

You can name the output file with -o like in the first synopsis. OR — plot twist — if you don't, then the first non-option filename argument gets taken as out.bam instead of being treated as an input file, which is the second synopsis. There's no default, bestie, none, so if you wanna write to standard output (or to a pipe) you gotta either say -o - or do the equivalent thing with - as the first filename argument. 🫶

Now. If you pass -h, the @SQ headers of the input files get merged into the header you specified. If you don't, they get merged into a composite header built out of the input headers. And heads up: if you're merging @SQ lines for coordinate sorted input files and a conflict pops up about order (say input1.bam has @SQ for a,b,c and input2.bam has b,a,c) then the resulting output file is gonna need to be re-sorted back into coordinate order. 😭 so watch for that.

Unless you specify -c or -p, when @RG and @PG records get merged into the output header, any IDs that turn out to be duplicates of IDs already chilling in the output header get a suffix slapped on them so they're differentiable from similar header records from other files — and the read records get updated to reflect that. ✨

Okay this next bit is important, don't scroll past it 🙈 — the ordering of the records in the input files has got to match the usage of the -n, -N, -t and --template-coordinate command-line options. If they don't match, the output order will be undefined. Yep, undefined. And this also extends to disallowing mixing of "queryname" files with a combination of natural and lexicographical sort orders. Peep sort for info about record ordering.

Also, problems can arise when you try to merge thousands of files together. The operating system may impose a limit on the maximum number of simultaneously open files — see ulimit -n for more info. And having many files read from simultaneously may cause a certain amount of "disk thrashing". To partially alleviate this, the merge command will load 1MB of data at a time from each file, but that in turn adds to the overall merge program memory usage. So please, please take this into account when setting memory limits. 🥺

In extreme cases, it may be necessary to reduce the problem to fewer files by successively merging subsets before a second round of merging. like, break it up into chunks, it's fine. 🧚

---

🎀 OPTIONS 🎀

• -1 — Use Deflate compression level 1 to compress the output. speedy lil thing ⚡
• -b FILE — List of input BAM files, one file per line. lowkey my fave way to hand over a big pile of inputs 📋
• -f — Force to overwrite the output file if present. no thoughts, just vibes, straight over the top 💀
• -h FILE — Use the lines of FILE as @ headers to be copied to out.bam, replacing any header lines that would otherwise be copied from in1.bam. (FILE is actually in SAM format, though any alignment records it may contain are ignored.) 👑
• -n — The input alignments are sorted by read names using an alpha-numeric ordering, rather than by chromosomal coordinates. The alpha-numeric or "natural" sort order detects runs of digits in the strings and sorts these numerically. Hence "a7b" appears before "a12b". Note this is not suitable where hexadecimal values are in use. 🔢
• -N — The input alignments are sorted by read names using a lexicographical ordering, rather than by chromosomal coordinates. Unlike -n no detection of numeric components is used, instead relying purely on the ASCII value of each character. Hence "x12" comes before "x7" as "1" is before "7" in ASCII. This is a more appropriate name sort order where all digits in names are already zero-padded and/or hexadecimal values are being used. 🅰️
• -o FILE — Write merged output to FILE, specifying the filename via an option rather than as the first filename argument. When -o is used, all non-option filename arguments specify input files to be merged. 🎯
• -t TAG — The input alignments have been sorted by the value of TAG, then by either position or name (if -n is given). 🏷️
• --template-coordinate — Input files are sorted by template-coordinate. 🧬
• -R STR — Merge files in the specified region indicated by STR [null]. 📍
• -r — Attach an RG tag to each alignment. The tag value is inferred from file names. 💖
• -u — Uncompressed BAM output. raw and unfiltered, we love to see it 🫧
• -c — When several input files contain @RG headers with the same ID, emit only one of them (namely, the header line from the first file we find that ID in) to the merged output file. Combining these similar headers is usually the right thing to do when the files being merged originated from the same file. Without -c, all @RG headers appear in the output file, with random suffixes added to their IDs where necessary to differentiate them. 🌈
• -p — Similarly, for each @PG ID in the set of files to merge, use the @PG line of the first file we find that ID in rather than adding a suffix to differentiate similar IDs. 🪄
• -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. See EXAMPLES section for sample of usage. 🗂️
• -L FILE — BED file for specifying multiple regions on which the merge will be performed. This option extends the usage of -R option and cannot be used concurrently with it. 🚫
• --no-PG — Do not add a @PG line to the header of the output file. quiet luxury 💅
• -@, --threads INT — Number of input/output compression threads to use in addition to main thread [0]. more threads more better ⚙️

---

🦋 EXAMPLES 🦋

💜 Attach the RG tag while merging sorted alignments

printf '@RG\tID:ga\tSM:hs\tLB:ga\tPL:ILLUMINA\n@RG\tID:454\tSM:hs\tLB:454\tPL:LS454\n' > rg.txt
samtools merge -rh rg.txt merged.bam ga.bam 454.bam

The value in a RG tag is determined by the file name the read is coming from. In this example, in the merged.bam, reads from ga.bam will be attached RG:Z:ga, while reads from 454.bam will be attached RG:Z:454. iconic behaviour, honestly 👑

💜 Include customized index file as a part of arguments

samtools merge [options] -X <out.bam> </data_folder/in1.bam> [</data_folder/in2.bam> ... </data_folder/inN.bam>] </index_folder/index1.bai> [</index_folder/index2.bai> ... </index_folder/indexN.bai>]

look at all those brackets. it's giving choose your own adventure 🧚

---

⭐ AUTHOR ⭐

Written by Heng Li from the Sanger Institute. legend behaviour fr fr 🙌

---

🌟 SEE ALSO 🌟

samtools(1), samtools-sort(1), sam(5)

Samtools website: <http://www.htslib.org/>

---

and that's the whole page, bestie!! 💖 it's samtools-1.24, dated 9 July 2026, and yeah — this was the samtools-merge(1) page. go merge something iconic. mwah 🫶✨🎀