samtools-fqidx(1)

✨ samtools fqidx — the fastq indexer/querier ✨

Okay bestie, so this is samtools-fqidx(1), part of the samtools fam 🧬 — it's the FASTQ cousin of faidx, and it's here to either build you an index or pull subsequences back out. Let's get into it 💅

---

💖 NAME 💖

samtools fqidx — it indexes, or queries regions out of, a fastq file. That's it, that's the whole vibe ✨

---

🎀 SYNOPSIS 🎀

samtools fqidx ref.fastq [region1 [...]]

---

🦋 DESCRIPTION 🦋

So here's the tea ☕: samtools fqidx will either index a reference sequence that's in FASTQ format, or extract a subsequence from an already-indexed reference sequence. Two modes, one tool, main character energy 👑

If you pass no region at all, fqidx just indexes the file and creates <ref.fastq>.fai right there on your disk 🫶.

If you do give it regions, then the subsequences get retrieved and printed to stdout in FASTQ format. Slay ✨

Your input and output can both be files compressed in BGZF format. When the output is compressed, the default compression level is 4 — that's the default, no cap.

⚠️ Heads up! The sequences in your input file really should all have different names. If they don't, indexing will yell at you with a warning about duplicate sequences, and retrieval will only ever produce subsequences from the first sequence with the duplicated name 😭. So like... rename your stuff, bestie.

💀 And this is a big one: samtools fqidx should only be used on fastq files with a small number of entries. If you try to use it on a file containing millions of short sequencing reads, you'll get an index that's almost as big as the original file, and searches using the index will be very slow and eat a lot of memory. Not the vibe. Not it at all 🙈.

---

🌸 OPTIONS 🌸

• -o, --output FILE — write the FASTQ to a file instead of to stdout. If FILE ends with .gz, .bgz or .bgzf then it gets BGZF compressed 💅
• -n, --length INT — the length used for FASTQ sequence line wrapping. If it's zero, that means do not line wrap at all. Defaults to the line length in the input file 🎀
• -c, --continue — keeps going even if you request a region that doesn't exist. Persistence, honestly ✨
• -r, --region-file FILE — reads regions from a file. The format is chr:from-to, one per line 🦋
• -i, --reverse-complement — outputs the sequence as the reverse complement. When you use this one, “/rc” gets appended to the sequence names. Wanna turn that off or change the string appended? That's what the --mark-strand option is for 🫶
• --mark-strand TYPE — appends a strand indicator to the sequence name. TYPE can be one of these:
  • rc — append '/rc' when writing the reverse complement. This is the default 👑
  • no — do not append anything. Minimalist 💅
  • sign — append '(+)' for forward strand or '(-)' for reverse complement. This matches the output of “bedtools getfasta -s” ✨
  • custom,<pos>,<neg> — append the string <pos> to names when writing the forward strand and <neg> when writing the reverse strand. Spaces are preserved, so it's totally possible to move the indicator into the comment part of the description line by including a leading space in the strings <pos> and <neg> 🎀
• --fai-idx FILE — read/write to the specified index file 🌸
• --gzi-idx FILE — read/write to the specified compressed file index (used with .gz files) 💜
• -h, --help — prints the help message and exits. Classic 🦋
• --output-fmt-option OPT=VAL — sets the output format options, e.g. level=0..9 for compression level 0 to 9 🔥
• --write-index — creates an index for the output sequence data right along with the output, in the same path as <output name>.fai, <outputname>.gzi. This option is valid only for file output, fyi ⭐
• -@, --threads N — sets the number of extra threads for operations on compressed files. Go fast, bestie 💀

---

👑 AUTHOR 👑

Written by Heng Li, with modifications by Andrew Whitwham and Robert Davies, all from the Sanger Institute. Legends, honestly 🫶

---

🌈 SEE ALSO 🌈

• samtools(1)
• samtools-faidx(1)
• samtools-fasta(1)
• samtools-fastq(1)

Samtools website: <http://www.htslib.org/> — go say hi 💖

---

Okay that's the whole page, bestie! This one's from samtools-1.24, dated 9 July 2026 — so mark your calendar and go index something small 🎀✨💅