Migrating to the standard library

In Python 3.14, the compression.zstd module is available to support Zstandard natively.

This guide was written to highlight the main differences and help with the migration.

Note that to support Python versions before 3.14, you will need to install the backports.zstd library, created by the maintainer of pyzstd.

The examples in this guide assume the following imports:

import pyzstd
import sys

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

level_or_option parameter

In pyzstd, the level_or_option parameter could accept either a compression level (as an integer) or a dictionary of options. In the standard library, this is split into two distinct parameters: level and options. Only one can be used at a time.

# before
pyzstd.compress(data, 10)
pyzstd.compress(data, level_or_option=10)

# after
zstd.compress(data, 10)
zstd.compress(data, level=10)

# before
pyzstd.compress(data, {pyzstd.CParameter.checksumFlag: True})
pyzstd.compress(data, level_or_option={pyzstd.CParameter.checksumFlag: True})

# after
zstd.compress(data, options={zstd.CompressionParameter.checksum_flag: True})

CParameter and DParameter

The CParameter and DParameter classes have been renamed to CompressionParameter and DecompressionParameter respectively.

Additionally, attribute names now use snake_case instead of camelCase.

# before
pyzstd.CParameter.enableLongDistanceMatching
pyzstd.DParameter.windowLogMax

# after
zstd.CompressionParameter.enable_long_distance_matching
zstd.DecompressionParameter.window_log_max

Finally, the CParameter.targetCBlockSize parameter is not available for now. Assuming a version of libzstd supporting it is used at runtime (1.5.6 or later), the integer 130 can be used as a key in the dictionary passed to the options parameter.

ZstdFile’s filename parameter

The first parameter of ZstdFile (filename) is now positional-only.

# before
pyzstd.ZstdFile("file.zst")
pyzstd.ZstdFile(fileobj)
pyzstd.ZstdFile(filename="file.zst")
pyzstd.ZstdFile(filename=fileobj)

# after
zstd.ZstdFile("file.zst")
zstd.ZstdFile(fileobj)

ZstdCompressor._set_pledged_input_size

The method _set_pledged_input_size of the ZstdCompressor class has been renamed to set_pledged_input_size.

EndlessZstdDecompressor

The EndlessZstdDecompressor class is not available.

Here are possible alternatives:

• Chain multiple ZstdDecompressor instances manually.

• Include this code snippet in your codebase.

• Use the decompress function if the data is small enough.

• Use a file-like interface via ZstdFile.

RichMemZstdCompressor and richmem_compress

The RichMemZstdCompressor class and richmem_compress function, which are deprecated in pyzstd, are not available.

Use compress instead (more details).

compress_stream and decompress_stream

The compress_stream and decompress_stream functions, which are deprecated in pyzstd, are not available.

See alternatives.

compressionLevel_values

The constant compressionLevel_values namedtuple is not available. Use the following alternatives:

• zstd.COMPRESSION_LEVEL_DEFAULT for the default compression level.

• zstd.CompressionParameter.compression_level.bounds() for the minimum and maximum compression levels.

Exceptions raised

The messages of raised exceptions are not always the same.

When they are due to an error in the parameters used by the caller, the type of exceptions may change as well.

# before
>>> pyzstd.compress(b'', {999:9999})
pyzstd.ZstdError: Zstd compression parameter "unknown parameter (key 999)" is invalid. (zstd v1.5.7)

# after
>>> zstd.compress(b'', options={999:9999})
ValueError: invalid compression parameter 'unknown parameter (key 999)'

ZstdFile

The read_size and write_size parameters of ZstdFile are not available.

ZstdDict

The is_raw parameter of ZstdDict is no longer positional. Call it by its name instead.

# before
pyzstd.ZstdDict(data, True)

# after
zstd.ZstdDict(data, is_raw=True)

SeekableZstdFile

Support for the Zstandard seekable format is not available. Continue using pyzstd for now if the feature is required.