BZ2File

0.98 · maintenance · verified Thu Apr 16

The `bz2file` library provides a file-like object for reading and writing bzip2-compressed files, backporting the `io.BZ2File` interface introduced in Python 3.3. While Python 3.3+ includes `bz2.open()` in its standard library, this standalone package serves as a drop-in replacement or for use with older Python versions (>=2.6, excluding 3.0-3.2). The current version is 0.98. It has an infrequent release cadence, being a stable backport.

Common errors

```
TypeError: a bytes-like object is required, not 'str'
```
cause Attempting to write a Python `str` object to a `BZ2File` opened in binary mode ('wb').

fix Convert the string to bytes before writing: `f.write("my data".encode('utf-8'))`.
```
ModuleNotFoundError: No module named 'bz2file'
```
cause The `bz2file` package has not been installed in the current Python environment.

fix Install the package using pip: `pip install bz2file`.
```
OSError: Invalid data stream
```
cause Attempting to open a file that is not a valid bzip2 compressed archive using `BZ2File`.

fix Ensure the file being opened is a correctly compressed bzip2 file. This error can also occur if the file is corrupted or truncated. Use standard file opening functions for uncompressed files.

Warnings

gotcha For new code on Python 3.3 and newer, consider using `bz2.open()` from the standard library's `bz2` module instead of this `bz2file` package. `bz2.open()` provides similar functionality and is built-in, making this external package largely redundant for modern Python versions.
Fix: Use `import bz2; with bz2.open('file.bz2', 'wb') as f:` for standard library usage.
gotcha When writing to a `BZ2File` opened in binary mode ('wb', 'ab'), input data must be `bytes` objects. Attempting to write `str` objects will result in a `TypeError`.
Fix: Encode string data to bytes explicitly before writing, e.g., `f.write('my string'.encode('utf-8'))`.
gotcha The `BZ2File` class, by default, operates in binary mode. If you need to read or write text, you must explicitly specify a text mode (e.g., `'wt'`, `'rt'`) and ideally an `encoding`.
Fix: For text, use `BZ2File('file.bz2', 'wt', encoding='utf-8')` for writing or `BZ2File('file.bz2', 'rt', encoding='utf-8')` for reading.

Install

pip install bz2file Install bz2file

Imports

BZ2File
wrong:
```
import bz2.BZ2File
```
correct:
```
from bz2file import BZ2File
```
The standard library's 'bz2' module exposes file operations via `bz2.open()`, not directly as `bz2.BZ2File`.

Quickstart

This quickstart demonstrates how to create and read a bzip2-compressed file using `BZ2File` in binary mode. It writes byte data, then reads it back to verify integrity.

import os
from bz2file import BZ2File

# Define a temporary file name
file_name = 'example.bz2'
data_to_write = b'This is some data that will be compressed using bzip2.'

# 1. Write compressed data to a .bz2 file
print(f"Writing to {file_name}...")
with BZ2File(file_name, 'wb') as f:
    f.write(data_to_write)
print("Write complete.")

# 2. Read compressed data from the .bz2 file
print(f"Reading from {file_name}...")
with BZ2File(file_name, 'rb') as f:
    read_data = f.read()
print(f"Read data: {read_data}")

assert read_data == data_to_write
print("Data integrity check passed.")

# Clean up the temporary file
os.remove(file_name)
print(f"Cleaned up {file_name}.")

view raw JSON →