backports.zstd 0.4.0

Backport of compression.zstd

backports.zstd

Backport of PEP-784 “adding Zstandard to the standard library”

---

📖 PEP-784   |   📃 Changelog   |   🎯 Roadmap

---

Install

Add the following dependency to your project:

backports.zstd ; python_version<'3.14'

…or just run pip install backports.zstd.

Usage

When importing a module needing Zstandard support, use a conditional import based on the version of Python. See below for examples.

zstd

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.

tarfile

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.

zipfile

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.

shutil

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.

FAQ

Who are you?

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).

How is this backport constructed?

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.

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.

Why can this library not be installed with Python 3.14?

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:

• During install;
• When importing at runtime.

What is the status of backports.zstd?

The code currently comes from CPython 3.14.0rc1. As a result, changes may appear upstream as we get closer to the final 3.14.0 release. We plan on releasing version 1.0.0 of backports.zstd together with release 3.14.0 of CPython.

However, this library can be used without waiting. At this point, backports.zstd is considered feature-complete, with support for CPython 3.9 to 3.13 (including free-threading support for 3.13). Support for PyPy is not yet available. See our roadmap for more information.

I found a bug

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!