Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Files, Paths and Text I/O

The gzip, bz2 and lzma modules

Reference for Python's gzip, bz2 and lzma modules: compress and decompress bytes, read and write compressed files, and choose between speed and size.

Three standard modules compress single streams of data: gzip (the DEFLATE algorithm, also behind .gz files and most web traffic), bz2 (.bz2, smaller but slower) and lzma (.xz, usually the smallest and the slowest to compress). They share almost the same interface, so learning one teaches you all three.

Each module offers two styles. The one-shot functions compress() and decompress() convert whole bytes objects in memory. The open() function returns a file object that compresses on write and decompresses on read, so you can treat a compressed file like a normal one, in binary or text mode.

Python
import gzip

packed = gzip.compress(b"hello " * 100)
original = gzip.decompress(packed)

Try it

Python Compress bytes in memory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Compressed files in text mode

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Main API

Name Description
gzip.compress(data, compresslevel=9) Returns gzip-compressed bytes.
gzip.decompress(data) Returns the original bytes. Raises gzip.BadGzipFile (an OSError) for invalid data.
gzip.open(filename, mode="rb", compresslevel=9, encoding=None) Opens a .gz file or file object. Use "rt"/"wt" for text, "rb"/"wb" for bytes, "ab" to append.
bz2.compress(data, compresslevel=9), bz2.decompress(data), bz2.open(...) The same interface for bzip2.
lzma.compress(data, format=FORMAT_XZ, preset=None), lzma.decompress(data), lzma.open(...) The same for LZMA/XZ. preset is 0 (fast) to 9 (small); LZMAError is raised on failure.
bz2.BZ2Compressor, BZ2Decompressor, lzma.LZMACompressor, LZMADecompressor Incremental objects for data that arrives in chunks.
zlib.compress(), zlib.decompress() The lower-level DEFLATE module that gzip and zipfile build on.

Usage notes

  • Compressing already compressed data wastes time. Images (JPEG, PNG), video, ZIP files and encrypted data barely shrink and may grow slightly.
  • Choosing a format. gzip is the fastest and the most widely supported; lzma gives the smallest files for archives you rarely write; bz2 sits in between and is used less often today. Lower compresslevel values trade size for speed.
  • Text mode needs an encoding. Pass encoding="utf-8" to open(..., "rt") and "wt"; otherwise the platform default applies.
  • Stream big files. Reading a huge file with .read() loads all of it into memory. Iterate over lines or read fixed-size chunks from the file object instead. For incremental compression of data that arrives in chunks, use the compressor and decompressor classes.
  • gzip files can contain several members joined together; decompress() and open() read them all as one stream.
  • Output of gzip.compress() has a timestamp in its header by default, so the bytes can differ between runs. Pass mtime=0 to gzip.compress() (Python 3.8+) when you need reproducible output.
  • Multiple files. These modules compress a single stream. To bundle files, use tarfile (.tar.gz, .tar.xz) or zipfile.
  • Python 3.14 adds a compression package that re-exports these modules under neutral names (compression.gzip, compression.bz2, compression.lzma) and adds compression.zstd for the Zstandard algorithm. The classic module names keep working.
  • In the browser runner all three modules work, but they run as WebAssembly, so keep test data small.