Add the following dependency to your project:
backports.zstd ; python_version<'3.14'
…or just run pip install backports.zstd.
When importing a module needing Zstandard support, use a conditional import based on the version of Python. See below for examples.
import sys
if sys.version_info >= (3, 14):
from compression import zstd
else:
from backports import zstd
# use the zstd module, for example:
zstd.compress(b"Hello, world!")Refer to the official Python documentation for usage of the module.
import sys
if sys.version_info >= (3, 14):
import tarfile
else:
from backports.zstd import tarfile
# use the tarfile module, for example:
with tarfile.open("archive.tar.zst") as tar:
tar.list()This tarfile modules is backported from Python 3.14 and includes Zstandard-specific
features such as: explicit modes for opening files (e.g. r:zstd), specific arguments
(e.g. zstd_dict)… refer to the official Python documentation for more
info.
Moreover, the CLI is available as well: python -m backports.zstd.tarfile.
import sys
if sys.version_info >= (3, 14):
import zipfile
else:
from backports.zstd import zipfile
# use the zipfile module, for example:
with zipfile.ZipFile("archive.zip", "w") as zf:
zf.writestr("hello.txt", "Hi!", zipfile.ZIP_ZSTANDARD)This zipfile modules is backported from Python 3.14 and includes Zstandard-specific
features such as the constant ZIP_ZSTANDARD to be used for compress_type… refer to
the official Python documentation for more info.
Moreover, the CLI is available as well: python -m backports.zstd.zipfile.
import shutil
import sys
if sys.version_info < (3, 14):
from backports.zstd import register_shutil
register_shutil()
# use the shutil module, for example
shutil.unpack_archive('archive.tar.zst')Calling the register_shutil function allows to create zstd'ed tar files using the
"zstdtar" format, as well as unpack them.
It also overrides support for unpacking zip files, enabling the unpacking of zip archives that use Zstandard for compression.
Alternatively, call register_shutil(tar=False) or register_shutil(zip=False) to
choose which archiving support to register.
This project is created and maintained by Rogdham
(maintainer of pyzstd, who helped with PEP-784
and integration of Zstandard into the standard library), with help from
Emma Smith (author of PEP-784, who did most of the
work of porting pyzstd into the standard library).
The aim is to be as close as possible to the upstream code of CPython.
The runtime code comes from CPython 3.14, with minor changes to support older versions of Python. For PyPy users, the C code has been ported to CFFI.
During the build phase, the project uses zstd
(canonical implementation of Zstandard) as well as
pythoncapi-compat (which handles some
of the compatibility with older Python versions).
Tests come from CPython 3.14, with minor changes to support older versions of Python.
Additional tests have been written specifically for backports.zstd.
The type hints for the standard library have been contributed to
typeshed and also backported to
backports.zstd.
This is on purpose. For Python
3.14 and later, use the compression.zstd module from the standard library.
If you want your code to be compatible with multiple Python versions, condition the usage of this library based on the Python version:
The wheels distributed on PyPI include a static version of libzstd for ease of
installation and reproducibility.
If you want to use libzstd installed on your system, pass the --system-zstd argument
to the build backend. For example:
python -m pip install --config-settings=--build-option=--system-zstd ...
python -m build --wheel --config-setting=--build-option=--system-zstd ...If you run the test suite, set the environment variable
BACKPORTSZSTD_SKIP_EXTENSION_TEST=1 to skip tests that may fail when using the system
library.
If you encounter any issues, please open a GitHub issue with a minimal reproducible example.
We will check if the issue is with backports.zstd or CPython. We have already reported
and fixed a few issues in CPython this way!