samtools-import(1)

samtools-import(1) 💅✨

okay so this is the <pink>samtools-import(1)</pink> page from the bioinformatics tools fam — like, the actual literal manual — and bestie, we're gonna get through it together, no cap 🫶

---

🌸 NAME 🌸

<mint>samtools import</mint> — converts FASTQ files to unmapped SAM/BAM/CRAM, slay 💖

---

✨ SYNOPSIS ✨

samtools import [options] [ fastq_file ... ]

---

🦋 DESCRIPTION 🦋

So basically it reads one or more FASTQ files and converts them into unmapped SAM, BAM or CRAM. The input files get automatically decompressed if they have a .gz extension — no extra steps, it just handles it for you 🔥

The simplest usage, when you have literally zero other command line options, is to just hand it one or two input files.

If you give it a single file, it gets interpreted as single-ended sequencing format — unless the read names end with /1 and /2, in which case they get labelled as PAIRED with the READ1 or READ2 BAM flags set. If you give it a pair of filenames, it reads from them alternately to produce an interleaved output file, and also sets the PAIRED and READ1 / READ2 flags 💫

You can also label the filenames explicitly: -1 and -2 for READ1 and READ2 data files, -s for an interleaved paired file (or one half of a paired-end run), -0 for unpaired data, and explicit index files with --i1 and --i2. These correspond to typical output produced by Illumina bcl2fastq and match the output from samtools fastq. The index files will set both the BC barcode code and its associated QT quality tag 🎀

The Illumina CASAVA identifiers can also be processed when the -i option is given. This tag gets processed for READ1 / READ2, whether or not the read failed processing (that's the QCFAIL flag), plus the barcode sequence, which gets added to the BC tag. This can be an alternative to explicitly specifying the index files — although, heads up, doing it this way will not fill out the barcode quality tag 🙈

---

🎀 OPTIONS 🎀

• -s FILE — import paired interleaved data from FILE.
• -0 FILE — import single-ended (unpaired) data from FILE.

okay so real talk: operationally there is no difference between the -s and -0 options. Like, give either one an interleaved file with /1 and /2 read name endings and both will correctly set the PAIRED, READ1 and READ2 flags. And give them data with no suffixes and no CASAVA identifiers being processed, and both will leave the data as unpaired. So why do they exist? Because more descriptive command lines are iconic, and it improves the header comment describing the samtools fastq decode command 💅

• -1 FILE, -2 FILE — import paired data from a pair of FILEs. The BAM flag PAIRED gets set, but not PROPER_PAIR, because hello, it hasn't been aligned. READ1 and READ2 get stored in their original, unmapped, orientation 🧚
• --i1 FILE, --i2 FILE — specifies index barcodes associated with the -1 and -2 files. These get appended to READ1 and READ2 records in the barcode (BC) and quality (QT) tags.
• -i — specifies that the Illumina CASAVA identifiers should be processed. This may set the READ1, READ2 and QCFAIL flags and add a barcode tag.
• -U, --UMI — migrates the UMI sequence from the last read name component to the UMI bar code 🔥
• --UMI-tag TAG — specifies which aux tag to place the UMI barcode into. Default is RX.
• -N, --name2 — assumes the read names are encoded in the SRA and ENA formats, where the first word is an automatically generated name with the second field being the original name. This option extracts that second field instead 👑
• --barcode-tag TAG — changes the auxiliary tag used for barcode sequence. Defaults to BC.
• --quality-tag TAG — changes the auxiliary tag used for barcode quality. Defaults to QT.
• -oFILE — output to FILE. By default output gets written to stdout.
• --order TAG — when outputting a SAM record, also outputs an integer tag containing the Nth record number. This may be useful if the data is to be sorted or collated in some manner and we want this to be reversible. In that case the tag may be used with samtools sort -t TAG to regenerate the original input order 🌀

⚠️ note: integer tags can only hold up to 2^32 record numbers (approximately 4 billion). Data sets with more records can switch to using a fixed-width string tag instead, with leading 0s to ensure sort works. To do this, specify TAG:LENGTH. E.g. --order rn:12 will be able to sort up to 1 trillion records. fr fr, that's a lot of records 💀

• -r RG_line, --rg-line RG_line — a complete @RG header line may be specified, with or without the initial "@RG" component. If specified, this will also use the ID field from RG_line in each SAM record's RG auxiliary tag.

If specified multiple times, this appends to the RG line, automatically adding tabs between invocations ✨

• -R RG_ID, --rg RG_ID — a shorter form of the option above, equivalent to --rg-line ID:RG_ID. If both are specified, then this option is ignored.
• -u — output BAM or CRAM as uncompressed data.
• -T TAGLIST — looks for any SAM-format auxiliary tags in the comment field of a fastq read name. These must match the <alpha-num><alpha-num>:<type>:<data> pattern as specified in the SAM specification. TAGLIST can be blank or * to indicate all tags should be copied to the output, otherwise it's a comma-separated list of tag types to include, with all others being discarded 🌈

---

💜 EXAMPLES 💜

Convert a single-ended fastq file to an unmapped CRAM. Both of these commands perform the same action.

samtools import -0 in.fastq -o out.cram
samtools import in.fastq > out.cram

Convert a pair of Illumina fastqs containing CASAVA identifiers to BAM, adding the barcode information to the BC auxiliary tag.

samtools import -i -1 in_1.fastq -2 in_2.fastq -o out.bam
samtools import -i in_[12].fastq > out.bam

Specify the read group. These commands are equivalent.

samtools import -r "$(echo -e 'ID:xyz\tPL:ILLUMINA')" in.fq
samtools import -r "$(echo -e '@RG\tID:xyz\tPL:ILLUMINA')" in.fq
samtools import -r ID:xyz -r PL:ILLUMINA in.fq

Create an unmapped BAM file from a set of 4 Illumina fastqs from bcf2fastq, consisting of two read and two index tags. The CASAVA identifier is used only for setting QC pass / failure status.

samtools import -i -1 R1.fq -2 R2.fq --i1 I1.fq --i2 I2.fq -o out.bam

Convert a pair of CASAVA barcoded fastq files to unmapped CRAM with an incremental record counter, then sort this by minimiser in order to reduce file space. The reversal process is also shown using samtools sort and samtools fastq 👑

samtools import -i in_1.fq in_2.fq --order ro -O bam,level=0 | \
    samtools sort -@4 -M -o out.srt.cram -

samtools sort -@4 -O bam -u -t ro out.srt.cram | \
    samtools fastq -1 out_1.fq -2 out_2.fq -i --index-format "i*i*"

---

🌟 AUTHOR 🌟

Written by James Bonfield of the Wellcome Sanger Institute. we stan 💖

---

🍓 SEE ALSO 🍓

samtools(1), samtools-fastq(1)

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

---

and that's the whole page, bestie!! 🌈✨ this was samtools-1.24, dated 9 July 2026, and it's the samtools-import(1) manual — go forth and convert those FASTQs, you absolute icon 👑🦋💅