Archives and compression

`bzip2`

Compress files to .bz2 with the Burrows-Wheeler algorithm, or decompress them with -d, bunzip2 or bzcat.

bzip2 [OPTION...] [FILE...]

9 of 9 examples run in Debian 13.7 on 2026-10-31 · manual: bzip2(1)

bzip2 works like gzip: bzip2 FILE replaces FILE with FILE.bz2, -d (or bunzip2) reverses it, -k keeps the original, -c writes to standard output, and bzcat prints a compressed file. It compresses one file at a time; directories go through tar -cjf to become .tar.bz2.

It usually beats gzip on size and is several times slower, particularly to decompress. Today xz compresses better and zstd is far faster at a similar ratio, so bzip2 mostly matters for reading the .bz2 files that older projects and data dumps still ship.

Unlike gzip, bzip2 has no -l to show sizes and no recursive mode. Its numeric options -1 to -9 set the block size (100k to 900k) rather than an effort level; the default is the largest, -9.

Examples

Compress a file, keeping the original

$ bzip2 -k access.log
> ls -l access.log*

output

-rw-rw-r-- 1 dev dev 2309 Oct 24 21:55 access.log
-rw-rw-r-- 1 dev dev  667 Oct 24 21:55 access.log.bz2

-k keeps access.log; without it the original is deleted. The .bz2 keeps the original's modification time.

See how much was saved

$ bzip2 -v data/users.csv data/sales.csv

explain

output

  data/users.csv:  1.503:1,  5.321 bits/byte, 33.49% saved, 436 in, 290 out.
  data/sales.csv:  2.045:1,  3.911 bits/byte, 51.11% saved, 405 in, 198 out.

-v prints the ratio, bits per byte, the percentage saved and the byte counts for each file. The originals are replaced by .bz2 files.

Decompress with -d or bunzip2

Setup run before this example

bzip2 todo.txt

$ bunzip2 todo.txt.bz2
> cat todo.txt

output

buy milk
fix login bug
write tests
fix logout bug
deploy v2.4

bunzip2 X is the same as bzip2 -d X. The .bz2 file is removed and todo.txt is back.

Read a compressed file without unpacking it

Setup run before this example

bzip2 access.log

$ bzcat access.log.bz2 | grep -c POST

explain

output

bzcat (same as bzip2 -dc) writes the decompressed text to standard output, here counted by grep. The .bz2 stays as it is.

Compress a stream

$ sort data/fruits.txt | bzip2 > fruits-sorted.bz2
> bzcat fruits-sorted.bz2 | head -n 4

output

apple
apple
apple
banana

Without file names bzip2 reads standard input and writes standard output, so it fits at the end of a pipeline.

Compare with gzip on the same file

$ gzip -9 -c access.log | wc -c
> bzip2 -9 -c access.log | wc -c

output

591
667

On this 2.3 KB log, gzip actually wins: bzip2's block sorting needs more data to pay off. On megabytes of text the order flips and bzip2 is usually clearly smaller than gzip.

Make and read a .tar.bz2

$ tar -cjf src.tar.bz2 src
> tar -tjf src.tar.bz2

output

src/
src/lib/
src/lib/helpers.py
src/util.sh
src/Makefile
src/main.c
src/app.py

-j tells tar to run the stream through bzip2. The listing shows every file under src/.

Check a file's integrity

Setup run before this example

bzip2 -k access.log
head -c 400 access.log.bz2 > cut.bz2

$ bzip2 -tv access.log.bz2
> bzip2 -t cut.bz2

outputexit 2

  access.log.bz2: ok
bzip2: cut.bz2: file ends unexpectedly

You can use the `bzip2recover' program to attempt to recover
data from undamaged sections of corrupted files.

-t decompresses in memory and verifies the checksums. With -v the good file reports ok; the truncated one ends unexpectedly, bzip2 points to bzip2recover for salvaging intact blocks, and the exit status is 2.

Decompressing over an existing file

Setup run before this example

bzip2 -k notes.txt

$ bzip2 -d notes.txt.bz2

explain

outputexit 1

bzip2: Output file notes.txt already exists.

notes.txt still exists, so bzip2 refuses to overwrite it and exits with 1. Add -f to overwrite, or -c to send the output somewhere else.

Common pitfalls

bzip2 file deletes file once the .bz2 is written. Use -k to keep it.
-1 to -9 choose the block size, not speed: lowering it saves memory but barely speeds up compression. For speed, use a different compressor.
bzip2 is single-threaded. On big files, pbzip2 or lbzip2 (separate packages) produce compatible output using every core.

GNU vs BSD and macOS

The examples above ran the GNU/Linux version. These are the differences that matter on macOS and the BSDs (written from their documentation, not run here).

bzip2 is the same program (bzip2 1.0.x) on Linux, macOS and the BSDs, so options behave alike.

Options worth knowing

A selection, described in our own words. For the full list, see bzip2(1) or bzip2 --help.

Option	What it does
`-d, --decompress`	Decompress instead of compress.
`-z, --compress`	Compress, even when invoked as bunzip2.
`-k, --keep`	Keep the input files.
`-f, --force`	Overwrite existing output files.
`-c, --stdout`	Write to standard output and keep the input.
`-t, --test`	Verify the integrity of compressed files.
`-q, --quiet`	Suppress non-essential warnings.
`-v, --verbose`	Print the compression ratio of each file; repeat for more detail.
`-s, --small`	Use less memory when decompressing, at the cost of speed.
`-1, --fast`	Use 100k blocks.
`-9, --best`	Use 900k blocks (the default).

Examples

Common pitfalls

GNU vs BSD and macOS

Options worth knowing

Related