bgzip(1)

💅 bgzip(1) — the block compression glow-up

ok so real talk, this is the bgzip page from the Bioinformatics tools manual set. It's the compression utility that's basically gzip's cooler older sister. Let's get into it 🎀

---

✨ NAME ✨

bgzip — Block compression/decompression utility. that's it, that's the whole vibe. it compresses, it decompresses, it does blocks. iconic.

---

🦋 SYNOPSIS 🦋

bgzip [-cdfhikrt] [-b virtualOffset] [-I index_name] [-l
compression_level] [-o outfile] [-s size] [-@ threads] [file ...]

look at all those little flags bestie, we're gonna go through every single one, don't worry 💖

---

🌸 DESCRIPTION 🌸

So bgzip compresses files in a way that's similar to — and honestly fully compatible with — gzip(1). The way it works is it chops your file up into a series of little (each less than 64K) blocks called 'BGZF' blocks. and why do we care?? because that means you can build indexes against the compressed file and then grab specific chunks of the data without having to decompress the entire file first. literally main character energy for random access 🔥

okay now the actual behaviour, pay attention:

• If you don't specify any files on the command line, bgzip will compress standard input to standard output (or decompress it, if you're using the -d option).
• If you do specify a file, it gets compressed (or decompressed with -d).
• If the -c option is used, the result goes to standard output instead.
• Otherwise, when compressing, bgzip writes to a new file with a .gz suffix and removes the original. yes, deletes it. be aware 🫶
• When decompressing, the input file must have a .gz suffix, which gets removed to make the output name. And again — after decompression finishes, the input file gets removed. so it's a whole swap situation.
• When you pass multiple files as input, the operation is performed on all of them.
• The access and modification time of the input file from the filesystem is set on the output file.

ngl, quick heads-up from the original: access time may get updated by the system whenever the system deems it appropriate. not our call, not our problem 💀

---

💅 OPTIONS 💅

• --binary — Bgzip will try to make sure BGZF blocks end on a newline when the input is a text file. The one exception is when a single line is bigger than a BGZF block (64Kb). This is handy for tools that use the index to do random access on the compressed stream, since the start of a block is likely to also be the start of a text record.

This option processes text files as if they were binary content — so it ignores where the newlines are. It also restores the behaviour for text files to bgzip version 1.15 and earlier. throwback 🕰️

• -b, --offset INT — Decompress to standard output starting from a virtual file position (that's a 0-based uncompressed offset). Implies -c and -d. so you get both, no extra charge ✨
• -c, --stdout — Write to standard output, keep original files unchanged. nice and non-destructive, we love her.
• -d, --decompress — Decompress. short and sweet 🍓
• -f, --force — Overwrite files without asking, or decompress files that don't have a known compression filename extension (like .gz) without asking. and here's the tea: use --force twice to do both of those without asking. yes, twice. don't skip that part.
• -g, --rebgzip — Try to use an existing index to create a compressed file with matching block offsets. The index must be specified using the -I file.gzi option.

⚠️ for real though: this assumes the same compression library and level are in use as when the original file was made. Don't use it unless you know what you're doing. like, actually know. i'm not kidding 😭

• -h, --help — Displays a help message. always there for you 🫶
• -i, --index — Create a BGZF index while compressing. Unless you use the -I option, the index will have the name of the compressed file with .gzi appended to it.
• -I, --index-name FILE — Index file name. you pick it, you own it 💅
• -k, --keep — Do not delete input file during operation. for when you're not ready to let go 🥺
• -l, --compress-level INT — Compression level to use when compressing. From 0 to 9, or -1 for the default level set by the compression library. [-1]
• -o, --output FILE — Write to a file, keep original files unchanged, and it will overwrite an existing file. no asking. so be careful which filename you type bestie 🙈
• -r, --reindex — Rebuild the index on an existing compressed file. glow-up for your .gzi ⭐
• -s, --size INT — Decompress INT bytes (uncompressed size) to standard output. Implies -c. snack-sized decompression 🍓
• -t, --test — Test the integrity of the compressed file. vibe check for your data 🔍
• -@, --threads INT — Number of threads to use [1]. yes the option is literally -@, she's quirky like that.

---

🌈 BGZF FORMAT 🌈

The BGZF format written by bgzip is described in the SAM format specification, which you can grab from http://samtools.github.io/hts-specs/SAMv1.pdf.

It makes use of a gzip feature that lets compressed files be concatenated. The input data is divided into blocks which are no larger than 64 kilobytes both before and after compression (including compression headers). Each block is compressed into a gzip file. The gzip header includes an extra sub-field with identifier 'BC' and the length of the compressed block, including all headers. cute little self-describing blocks, obsessed 💜

---

🧚 GZI FORMAT 🧚

The index format is a binary file listing pairs of compressed and uncompressed offsets in a BGZF file. Each compressed offset points to the start of a BGZF block. The uncompressed offset is the corresponding location in the uncompressed data stream.

All values are stored as little-endian 64-bit unsigned integers. no cap.

The file contents are:

uint64_t number_entries

followed by number_entries pairs of:

uint64_t compressed_offset
uint64_t uncompressed_offset

look at that struct energy, so clean 🎀

---

🔥 EXAMPLES 🔥

# Compress stdin to stdout
bgzip < /usr/share/dict/words > /tmp/words.gz

# Make a .gzi index
bgzip -r /tmp/words.gz

# Extract part of the data using the index
bgzip -b 367635 -s 4 /tmp/words.gz

# Uncompress the whole file, removing the compressed copy
bgzip -d /tmp/words.gz

copy-paste these, they ate 💅

---

👑 AUTHOR 👑

The BGZF library was originally implemented by Bob Handsaker and modified by Heng Li for remote file access and in-memory caching. legends, honestly 🫶

---

🌟 SEE ALSO 🌟

gzip(1), tabix(1) — go read those next, iykyk

---

okay that's the whole page bestie!! and for the credits portion of our show: this lovely document is from htslib-1.24, dated 9 July 2026, living in the Bioinformatics tools manual family. bye, love you, compress responsibly 💖🦋✨