Install & Compatibility
Where this runs
tested against v1.7.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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.0s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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+.
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
Debug
Known issues
breakingThis 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.fixRemove `backports.zstd` from dependencies for Python 3.14+ environments and use `from compression import zstd` directly. Conditional imports are recommended for multi-version compatibility.
affects: >=3.14
deprecatedThe `backports.zstd` library is scheduled for deprecation with the end of official support for Python 3.13 (October 2029).fixPlan 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.
affects: All versions
gotchaFor code compatible with both Python versions below 3.14 and 3.14+, a conditional import statement is required to correctly import the `zstd` module.fixImplement conditional imports like `if sys.version_info >= (3, 14): from compression import zstd else: from backports import zstd`.
affects: <3.14 and >=3.14
gotchaBy 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.fixWhen installing, use `pip install --config-settings=--build-option=--system-zstd backports.zstd`. During testing with system `libzstd`, set `BACKPORTSZSTD_SKIP_EXTENSION_TEST=1`.
affects: All versions
Upgrade
Version history
1.7.0latest on PyPI · released Aug 15, 2026
Audit
Dependencies
libzstdoptionalProvides the underlying Zstandard compression algorithm. A static version is bundled, but a system-installed version can be used with a specific build option.
pythoncapi-compatrequiredUsed during the build phase for compatibility with older Python versions.