Registry / serialization / zstd
library1.5.7.2pypypi✓ verified 24d ago

The 'zstd' library provides fast Python bindings to Yann Collet's Zstandard (zstd) lossless compression algorithm. It offers a compelling balance of speed and compression ratio, making it a popular choice for real-time compression and large-scale data processing. The library is actively maintained with frequent releases, currently at version 1.5.7.3, and focuses on performance optimizations and bug fixes.

pip install zstd
INSTALL
IMPORT
SIG · ZSTD
Z
zstd
serializationpythonv1.5.7.2
Install
1.9s avg
Import
Disk
21MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.5.7.2 · 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
musl
glibc
py 3.10
✓ —
✓ 1.8s
py 3.11
✓ —
✓ 1.7s
py 3.12
✕ build_error
✓ 2.3s
py 3.13
✕ build_error
✓ 1.7s
py 3.9
✓ —
✓ 2s
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

zstd
import zstd
import zstandard
The PyPI package `zstd` (or `python-zstd`) exposes its API directly under the `zstd` module name. `zstandard` is a separate, distinct Python library for Zstandard.

Demonstrates basic one-shot compression and decompression of bytes data using `zstd.compress()` and `zstd.decompress()`. It also includes an example of streaming compression/decompression for larger datasets, highlighting the use of `ZstdCompressor` and `ZstdDecompressor` and the importance of flushing.

import zstd original_data = b"This is some data that will be compressed using Zstandard. It\'s a fairly long string to demonstrate compression efficiency." * 100 # Compress data # level can range from -100 (ultra-fast) to 22 (slowest, best compression) # threads can be 0 (auto-tune) or a specific number compressed_data = zstd.compress(original_data, level=3, threads=0) print(f"Original size: {len(original_data)} bytes") print(f"Compressed size: {len(compressed_data)} bytes") print(f"Compression ratio: {len(compressed_data) / len(original_data):.2f}") # Decompress data decompressed_data = zstd.decompress(compressed_data) assert original_data == decompressed_data print("Decompression successful! Data matches original.") # Example of streaming compression for large data cctx = zstd.ZstdCompressor(level=1) dctx = zstd.ZstdDecompressor() chunk_size = len(original_data) // 5 compressed_chunks = [] # Stream compress for i in range(0, len(original_data), chunk_size): chunk = original_data[i:i + chunk_size] compressed_chunk = cctx.compress(chunk) compressed_chunks.append(compressed_chunk) # Important: flush the compressor to finalize the frame compressed_chunks.append(cctx.flush()) streaming_compressed_data = b''.join(compressed_chunks) # Stream decompress streaming_decompressed_data = dctx.decompress(streaming_compressed_data) assert original_data == streaming_decompressed_data print("Streaming decompression successful! Data matches original.")
zstd --version
Debug
Known issues
breakingStarting with Python 3.14, a new `compression.zstd` module will be added to the standard library (PEP 784). This may cause import ambiguities or conflicts if the third-party `zstd` package is also installed and `import zstd` is used directly, as the standard library module might take precedence or behave differently.
fix
For Python 3.14+, explicitly use `from backports import zstd` if you intend to use the PyPI `zstd` package, or adapt your code to use the standard library's `from compression import zstd` module. For cross-version compatibility, use conditional imports (`if sys.version_info >= (3, 14): from compression import zstd else: import zstd`).
affects: Python 3.14+
gotchaUsing `zstd.compress()` or `zstd.decompress()` with extremely large datasets (e.g., multi-gigabyte files) can lead to significant memory consumption as the entire input/output must fit in memory simultaneously. This can result in `MemoryError`.
fix
For large datasets, use the streaming APIs provided by `zstd.ZstdCompressor` and `zstd.ZstdDecompressor` which process data in chunks, keeping memory usage manageable. Ensure files are opened in binary mode ('rb', 'wb') for streaming I/O.
affects: All versions
gotchaWhen using `ZstdCompressor` for incremental compression, it is crucial to call its `flush()` method after providing all input data to ensure that all buffered compressed data is emitted and the Zstandard frame is properly finalized. Failing to do so can result in incomplete or corrupted compressed data that cannot be decompressed correctly by other tools or even the same library.
fix
Always call `compressor.flush()` after the last `compressor.compress()` call to finalize the frame. Using `ZstdCompressor` as a context manager (e.g., `with cctx.stream_writer(fh) as compressor: ...`) can help ensure flushing is handled automatically upon exiting the block.
affects: All versions
breakingIn version 1.5.7.1, the `ZSTD_min_compression_level()` function was fixed to return a 'real number' (likely a standard integer representing the level) instead of a 'shifted int value'. If previous code relied on the specific bitwise representation or shifted value returned by this function, its behavior will change.
fix
Review any code that calls `zstd.ZSTD_min_compression_level()` and adapt it to expect a standard integer value for the compression level. Most users are unlikely to be directly affected unless interacting with this specific low-level function.
affects: 1.5.7.1 and later
Errors
Common errors & fixes
error: Failed to find zstd library, please install zstd development headers and static library (or similar: 'zstd.h not found')
The Python `zstd` library is a wrapper around the C `zstd` library; during installation, it requires the C development headers and static library to compile its C extensions.
fix
Install the Zstandard development packages specific to your operating system. For Debian/Ubuntu: `sudo apt-get update && sudo apt-get install libzstd-dev`. For RedHat/CentOS: `sudo dnf install libzstd-devel` or `sudo yum install libzstd-devel`. For macOS (Homebrew): `brew install zstd`.
ModuleNotFoundError: No module named 'zstd'
The `zstd` Python package has not been installed in the current Python environment, or the environment is not correctly activated.
fix
Install the package using pip: `pip install zstd`
zstd.ZstdError: Decompression error: Corrupted block detected (or: Invalid frame / Not a zstd frame)
The input data provided to the decompressor is either not valid Zstandard compressed data, has been truncated, or is corrupted.
fix
Ensure the data being passed to the `zstd` decompressor was genuinely compressed using Zstandard and has not been altered or partially read. Verify the source and integrity of the compressed data.
MemoryError
Attempting to compress or decompress an extremely large dataset entirely in memory without streaming or chunking, thereby exceeding available RAM.
fix
For very large data, use `zstd.ZstdCompressor` and `zstd.ZstdDecompressor` in streaming mode by feeding data in manageable chunks (e.g., using `compress_stream` / `decompress_stream` or `stream_writer` / `stream_reader`).
Upgrade
Version history
1.5.7.2latest on PyPI · released Jun 23, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
63 hits · last 30 days
node
54
OpenAI (training)
2
Resources
zstd — pip install zstd · libregistry