bzip3(1)

💖 bzip3(1) — the General Commands Manual, but make it cute 💖

okay so bestie, listen. this is the manual for bzip3, and yes it lives in the General Commands Manual section (that's the (1) part, iykyk). sit down, hydrate, and let me tell you about the most iconic little compressor in the game. 🎀

---

✨ NAME ✨

bzip3 — an efficient statistical file compressor and spiritual successor to bzip2. not just a successor, the spiritual successor. it's giving legacy. it's giving lineage. 💅

---

🦋 SYNOPSIS 🦋

bzip3 [ -BbcdehftV ] [ filenames ... ]

bz3cat is equivalent to bzip3 -dc

bunzip3 is equivalent to bzip3 -d

three names, one queen. that's range. 🌈

---

🌸 DESCRIPTION 🌸

okay so what does it actually DO. bzip3 compresses or decompresses a file using run length encoding and Lempel Ziv prediction, followed by the Burrows-Wheeler transform and arithmetic coding. that's four whole transformations stacked in a trench coat and honestly? it ate. 🔥

bzip3, like its ancestor bzip2, excels at compressing text or source code. so your 40,000-line main.rs? handled. your lore doc? compressed. periodt.

the command-line options are deliberately very similar to those of bzip2, but they are not identical. so don't get cute and assume, bestie. lowkey they're cousins, not twins. 🙈

bzip3 expects at most two filenames intertwined with flags. and by default it will not overwrite existing files — it is a considerate queen. if overwriting is actually what you intend, use the -f flag. (that's the chaos flag. use responsibly.)

if no file names are specified, bzip3 will compress from standard input to standard output, refusing to output binary data to a terminal. the -e flag (encode) is implied. it said "no binary to your terminal, i'm protecting you", and honestly, protect me bestie. 🫶

bunzip3 (or, bzip3 -d equivalently) decompresses data from standard input to the standard output, refusing to read from a terminal.

if two files are specified, the first one is used in place of standard input, and the second one is used in place of standard output. very "you be stdin, you be stdout, i'll direct the traffic". ✨

if the -c flag is present, bzip3 will read from the specified file and output data to standard output instead. otherwise, if decoding, bzip3 will try to guess the decompressed filename by removing the .bz3 extension. if it's not present, an error will be reported. if encoding, the output filename will be generated by appending the .bz3 extension to the input filename. naming? automated. vibes? immaculate. 💅

---

✨ OPTIONS ✨

one bullet per flag, no skips, no summaries, we respect the source material in this house.

• -B, --batch — enable batch mode. by default, bzip3 will error if more than two files are passed, and the two files specified are always treated as input and output. batch mode makes bzip3 treat every file as input, so for example bzip3 -Bd *.bz3 will decompress all .bz3 files in the current directory. it's the "do the whole friend group" setting. 👑
• -b, --block N — set the block size to N mebibytes. the minimum is 1MiB, the maximum is 511MiB. the default is 16MiB. tiny or enormous, your call. 🍓
• -c, --stdout — force writing output data to the standard output if one file is specified.
• -d, --decode — force decompression.
• -e, -z, --encode — force compression (default behaviour). yes it's the default, no we're not skipping it, rules are rules. 💖
• -f, --force — overwrite existing files. this is the "i said what i said" flag. 😭
• -h, --help — display a help message and exit.
• -j, --jobs N — set the amount of parallel worker threads that process one block each. default is to use 1 worker thread. give it more threads, give it more friends. 🧚
• --rm — remove the input files after successful compression or decompression. this is silently ignored if output is stdout. (silently. it will not warn you. it will not text you back. 💀)
• -k, --keep — keep (don't delete) the input files. set by default, provided only for compatibility with other compressors. so it's basically decorative but we love her anyway. 🎀
• -v, --verbose — set verbose output mode to see compression statistics. numbers! graphs-adjacent content! obsessed. 📊
• -V, --version — display version information and exit.
• -t, --test — verify the validity of compressed blocks. a little wellness check for your archives. 🫶
• -- — treat all subsequent arguments as file names, even if they start with a dash. this is so you can handle files with names beginning with a dash. the classic "my filename starts with - and now the shell is fighting me" rescue. ✨

---

🌈 FILE FORMAT 🌈

compression is performed as long as the input block is longer than 64 bytes. otherwise, it's coded as a literal block. in all other cases, the compressed data is written to the file. so: tiny blocks get the literal treatment, everyone else gets the whole pipeline. ⭐

the file format has constant overhead of 9 bytes per file and from 9 to 17 bytes per block.

random data is coded so that expansion is generally under 0.8%. yes bestie, it can grow a little on pure chaos data — but under 0.8%, which is basically nothing. it's fine. we're fine. 💜

bzip3 uses 32-bit CRC to ensure that the decompressed version of a file is identical to the original. this guards against corruption of the compressed data. it's the "i checked, and i'm checking again" energy. no cap. 🔥

---

🎀 MEMORY MANAGEMENT 🎀

the -b flag sets the block size in mebibytes (MiB). the default is 16 MiB. compression and decompression memory usage can be estimated as:

6 x block size

literally just six times your block size. that's the math. that's the whole math. 🧮✨

larger block sizes usually give rapidly diminishing returns. it is also important to appreciate that the decompression memory requirement is set at compression time by the choice of block size. (read that again — the compression settings decide how much RAM decompression will demand later. it's a whole relationship. 💀)

in general, try and use the largest block size memory constraints allow, since that maximises the compression achieved. compression and decompression speed are virtually unaffected by block size. so big block = more squeeze, same speed, just remember the 6 x memory bill. slay. 💅

---

👑 AUTHOR 👑

Kamila Szewczyk, k@iczelia.net.

https://github.com/iczelia/bzip3

thanks to: Ilya Grebnov, Benjamin Strachan, Caleb Maclennan, Ilya Muravyov, package maintainers — Leah Neukirchen, Grigory Kirillov, Maciej Barc, Robert Schutz, Petr Pisar, Przemyslaw Skibinski, Shun Sakai and others. also everyone who sent patches, helped with portability problems, encouraged me to work on bzip3 and lent me machines for performance tests.

the way that whole list is a hall of fame and they're all getting flowers. 🌸🫶

---

💜 SEE ALSO 💜

bzip2(1), bz3less(1), bz3more(1), bz3grep(1), bunzip3(1)

go read them, they're the extended universe. 🌈

---

and that's the page bestie!! this was version v1.5.5, dated 22 October 2026, and it's the bzip3(1) manual — now go compress something and think of me. 💖✨ mwah. 🎀