Backports Zstandard (zstd)

1.3.0 · active · verified Sun Mar 29

backports-zstd is a library that backports the `compression.zstd` module, introduced in Python 3.14, to older Python versions (3.9 to 3.13). It provides a Pythonic interface for Zstandard compression, aiming to be as close as possible to the standard library's implementation. The library is currently at version 1.3.0 and is actively maintained, though it is designed to be superseded by the standard library module in Python 3.14 and later.

Warnings

breaking This library is intentionally not installable on Python 3.14 or later. For Python 3.14+, the `compression.zstd` module is part of the standard library and should be used directly.
Fix: Remove `backports.zstd` from dependencies for Python 3.14+ environments and use `from compression import zstd` directly. Conditional imports are recommended for multi-version compatibility.
deprecated The `backports.zstd` library is scheduled for deprecation with the end of official support for Python 3.13 (October 2029).
Fix: Plan to migrate to `compression.zstd` in the Python standard library as projects transition to Python 3.14 or newer. Conditional imports will facilitate this transition.
gotcha For code compatible with both Python versions below 3.14 and 3.14+, a conditional import statement is required to correctly import the `zstd` module.
Fix: Implement conditional imports like `if sys.version_info >= (3, 14): from compression import zstd else: from backports import zstd`.
gotcha By default, `backports.zstd` uses a statically bundled `libzstd`. If you prefer to use a system-installed `libzstd`, you must pass a specific argument during the build phase.
Fix: When installing, use `pip install --config-settings=--build-option=--system-zstd backports.zstd`. During testing with system `libzstd`, set `BACKPORTSZSTD_SKIP_EXTENSION_TEST=1`.

Install

pip install "backports.zstd; python_version < '3.14'" Conditional installation for Python < 3.14
pip install backports.zstd Standard installation (will respect python_requires)

Imports

zstd
```
import sys
if sys.version_info >= (3, 14):
    from compression import zstd
else:
    from backports import zstd
```
Conditional import is crucial for compatibility across Python 3.9+ where 'compression.zstd' is native in 3.14+.

tarfile

import sys
if sys.version_info >= (3, 14):
    import tarfile
else:
    from backports.zstd import tarfile

Conditional import for Zstandard-aware tarfile module.

zipfile

import sys
if sys.version_info >= (3, 14):
    import zipfile
else:
    from backports.zstd import zipfile

Conditional import for Zstandard-aware zipfile module.

register_shutil
```
import sys
if sys.version_info < (3, 14):
    from backports.zstd import register_shutil
    register_shutil()
```
Registers Zstandard support with the shutil module for older Python versions. Not needed for Python 3.14+.

Quickstart

Demonstrates how to conditionally import the `zstd` module and perform basic compression and decompression of byte data. This pattern ensures your code works across Python versions where `compression.zstd` is either in the standard library or provided by the backport.

import sys

if sys.version_info >= (3, 14):
    from compression import zstd
else:
    from backports import zstd

original_data = b"Hello, Zstandard backport! " * 100

# Compress data
compressed_data = zstd.compress(original_data)
print(f"Original size: {len(original_data)} bytes")
print(f"Compressed size: {len(compressed_data)} bytes")

# Decompress data
decompressed_data = zstd.decompress(compressed_data)
print(f"Decompressed size: {len(decompressed_data)} bytes")
assert original_data == decompressed_data

view raw JSON →