The BZ2 file (.bz2)

A BZ2 file is one file compressed with bzip2. dump.sql becomes dump.sql.bz2, and decompressing it gives back the original exactly. Like gzip, bzip2 compresses a single file and has no idea of folders; a folder is first bundled with tar, giving a .tar.bz2 (or .tbz2) file.

Julian Seward released bzip2 in 1996. For text it compressed noticeably better than gzip, so through the late 1990s and 2000s many open-source projects published .tar.bz2 downloads next to .tar.gz. Since then most have moved on to XZ or Zstandard, which compress about as well and decompress much faster.

You still meet .bz2 in older software archives, scientific data sets, and Wikipedia's database dumps, which use a multi-stream bzip2 layout so that single articles can be read without decompressing everything.

gzip and xz look back for repeated strings. bzip2 does something different: it rearranges each block so that similar bytes end up next to each other, then compresses the result. The stages, in order:

1. 1Run-length encoding: runs of 4 to 255 identical bytes are shortened first.
2. 2Burrows-Wheeler transform (BWT): imagine every rotation of the block, sorted alphabetically. The last letter of each sorted rotation is written out. Because similar contexts sort together, this output has long runs of the same character. It's reversible with one extra number, the origin pointer.
3. 3Move-to-front: each byte is replaced by its position in a list of recently seen bytes, so those runs turn into lots of zeros and small numbers.
4. 4Run-length encoding of zeros, then Huffman coding with up to six code tables, switching table every 50 symbols to suit the data.

Each block is compressed on its own, which has three consequences. Bigger blocks (-9, the default) give the sorting more to work with and compress better. Blocks can be compressed in parallel: pbzip2 and lbzip2 use every CPU core and write files any bzip2 can read. And damage stays local: bzip2recover can rescue the intact blocks of a broken file.

bzip2 is modest with memory. At -9, the bzip2 manual gives about 7.6 MB to compress and 3.7 MB to decompress, or 2.35 MB with the slower -s option. Lower levels need less.

On this text-heavy data, bzip2 made the smallest file of the three and compressed six times faster than xz. Its weak point is decompression: about seven times slower than gzip and three times slower than xz. For a download that's compressed once and unpacked many times, that's the wrong way round, which is the main reason projects switched to xz. On other data, especially binaries, xz usually compresses better than bzip2 as well. The XZ page has the full table, including Zstandard and ZIP.

Two bzip2 files joined with cat a.bz2 b.bz2 > both.bz2 form a valid multi-stream file, and bunzip2 decompresses both. Parallel compressors such as pbzip2 write files like that. Not every library reads past the first stream: Python's bz2 module has done so since Python 3.3, while Apache Commons Compress only does when its decompressConcatenated option is on. sample-multi-stream.bz2 tests exactly this.

• bunzip2 deleted the .bz2 file. Like gzip, bzip2 replaces the input by default. Use -k to keep it.
• The name came out different. bzip2 stores no name; it drops .bz2, and turns .tbz2 and .tbz into .tar.
• (stdin) is not a bzip2 file: the data doesn't start with BZh. It may be a gzip or XZ file with the wrong extension; file name.bz2 tells you.
• Compressed file ends unexpectedly: the file was cut short. Run bzip2recover name.bz2 to save the complete blocks into separate files.
• Slow to unpack a big archive: lbzip2 -d decompresses on all CPU cores. pbzip2 -d does too, but only for files that pbzip2 made.

• Linux and macOS: bunzip2 file.bz2 (or bzip2 -d) to decompress, bzip2 -k file to compress and keep the original, bzcat and bzless to read without unpacking. For a .tar.bz2, tar -xf file.tar.bz2 and tar -cjf archive.tar.bz2 folder/. On a Mac, double-clicking also usually works.
• Windows: recent Windows 11 opens .tar.bz2 and .tbz2 archives in File Explorer. For a plain .bz2, or on Windows 10, use a free tool such as 7-Zip or PeaZip.
• Programming: Python's bz2 module, Java's Apache Commons Compress, Go's compress/bzip2 (decompression only) and libbzip2 for C.
• Convert to XZ or gzip: bzcat file.bz2 | xz -9 > file.xz, or for a tarball, bzcat project.tar.bz2 | gzip > project.tar.gz. The tar inside doesn't change.

Decompressing runs no code from the file. The things to watch:

• Extreme expansion. Because bzip2 run-length encodes before anything else, repetitive data shrinks dramatically. In our test, 1 GiB of zero bytes compressed to 785 bytes with bzip2 -9, a ratio of over a million to one (gzip managed about a thousand to one on the same input). Code that decompresses uploads must cap the output size, not trust the input size.
• Old decoder bugs. bzip2 before version 1.0.7 had a memory corruption bug triggered by crafted files (CVE-2019-12900). Keep bzip2 and libraries that bundle it up to date.
• What's inside. A .tar.bz2 brings the tar risks of ../ paths and symbolic links, explained on the TAR page, and any file can contain malware.