Install & Compatibility
Where this runs
tested against v2.11.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cramjam
✓ import cramjam
General import for accessing all compression variants (e.g., cramjam.snappy, cramjam.brotli).
snappy
✓ from cramjam import snappy
Import a specific compression algorithm directly.
Buffer
✓ from cramjam import Buffer
Used for efficient in-memory buffer operations, particularly with de/compress_into methods.
This quickstart demonstrates basic compression and decompression using Snappy and Brotli. It also includes an example of using `cramjam.Buffer` for more efficient in-place compression operations, which is beneficial when dealing with `bytes`, `bytearray`, or `numpy.array` objects.
import cramjam
original_data = b"This is some data to compress using cramjam!"
# Compress data using Snappy
compressed_data = cramjam.snappy.compress(original_data)
print(f"Original size: {len(original_data)} bytes")
print(f"Compressed size (Snappy): {len(compressed_data)} bytes")
# Decompress data
decompressed_data = cramjam.snappy.decompress(compressed_data)
print(f"Decompressed data matches original: {original_data == decompressed_data}")
# Example with Brotli
compressed_brotli = cramjam.brotli.compress(original_data)
print(f"Compressed size (Brotli): {len(compressed_brotli)} bytes")
decompressed_brotli = cramjam.brotli.decompress(compressed_brotli)
print(f"Decompressed Brotli matches original: {original_data == decompressed_brotli}")
# Using cramjam.Buffer for in-place operations
from cramjam import snappy, Buffer
import numpy as np
data_np = np.frombuffer(b'some bytes here for buffer', dtype=np.uint8)
output_buffer = Buffer()
snappy.compress_into(data_np, output_buffer)
output_buffer.seek(0) # Reset buffer position for reading
decompressed_buffer_data = snappy.decompress(output_buffer)
print(f"Buffer decompressed data matches original: {bytes(data_np) == bytes(decompressed_buffer_data)}")
Debug
Known issues
gotchaWhen integrating `cramjam`'s LZ4 implementation or migrating from other LZ4 libraries, be aware that the default compression level in `cramjam`'s LZ4 might differ. For example, a change from level 0 to 9 in a dependent library using `cramjam`'s LZ4 was observed to cause significant performance degradation (over 100% latency increase) if not explicitly set. Always verify the `compression_level` if performance is critical.fixExplicitly set the `compression_level` parameter when calling `cramjam.lz4.compress` or ensure any integrating library configures it appropriately. The default behavior may vary and impact performance.
affects: All versions (behavioral difference)
gotchaFor significant performance improvements (1.5-3x speedup), especially when decompressing or compressing to a standard `bytes` or `bytearray` object, provide the `output_len` argument if the exact output length is known beforehand. This allows for single buffer allocation. This optimization is less relevant when using `cramjam.Buffer` or `cramjam.File` objects.fixPass the `output_len=some_integer` argument to `compress` or `decompress` functions when the final size is predictable.
affects: All versions
gotchaSome compression algorithms (e.g., Blosc2, ISA-L backends like igzip, ideflate, izlib) are considered experimental. These typically require building `cramjam` from source with specific feature flags enabled. They are not available out-of-the-box with a standard `pip install`.fixRefer to the official `cramjam` GitHub repository or documentation for instructions on building from source with experimental features if you need to use them.
affects: All versions
breakingThe test script or some functionalities within `cramjam` rely on `numpy`, which is not installed by default in the test environment. This results in a `ModuleNotFoundError` if `numpy` is not available.fixEnsure `numpy` is installed in your environment by running `pip install numpy`.
affects: All versions
breakingWhen running `cramjam` on minimal Linux distributions like Alpine, especially with Python versions that might not have readily available pre-built wheels, core compression/decompression functionalities (e.g., Snappy, Brotli) might fail to correctly decompress data, resulting in `Decompressed data matches original: False`. This typically occurs if `cramjam`'s Rust extensions are not compiled against the correct system libraries, or if necessary build dependencies are missing during installation. Always verify `cramjam`'s functionality on Alpine if you are using it.fixEnsure that `cramjam` is installed from a compatible wheel for your Alpine Python environment, or install necessary build tools (e.g., `rust`, `cargo`, `musl-dev`, `python3-dev`, `build-base`) before installing `cramjam` to allow it to compile correctly from source. Test core compression/decompression functionality after installation.
affects: All versions (platform-specific behavioral difference on Alpine/musl-based systems)
Upgrade
Version history
2.12.1latest on PyPI · released Aug 25, 2026
Audit
Dependencies
pythonrequiredRequired for running the Python bindings.