Install & Compatibility
Where this runs
tested against v? · pip install
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.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
zipfile_zstd
✓ import zipfile_zstd
Importing this module performs the monkey-patch to enable Zstandard support in the standard `zipfile` module. It also provides `ZIP_ZSTANDARD` constant.
ZIP_ZSTANDARD
✓ from zipfile_zstd import ZIP_ZSTANDARD
✗ from zipfile import ZIP_ZSTANDARD
The `ZIP_ZSTANDARD` constant is added by `zipfile-zstd` to the `zipfile` module after patching, or can be imported directly from `zipfile_zstd` for clarity. Attempting to import it directly from the standard `zipfile` without the patch will fail on Python versions < 3.14.
This quickstart demonstrates how to create a ZIP archive using Zstandard compression and then extract its contents. It first enables the `zipfile-zstd` monkey-patch, then uses the standard `zipfile.ZipFile` class with the `ZIP_ZSTANDARD` constant for compression. It concludes with cleanup of the created files.
import zipfile_zstd
import os
from pathlib import Path
# Enable Zstandard support for the standard zipfile module
zipfile_zstd.enable_zstandard()
# ZIP_ZSTANDARD constant is now available in the patched zipfile module
# or can be imported directly from zipfile_zstd
from zipfile_zstd import ZIP_ZSTANDARD
import zipfile # The standard zipfile module is now patched
archive_name = "example_zstd.zip"
file_to_compress = "test_file.txt"
extracted_dir = "extracted_zstd"
# Create a dummy file for compression
Path(file_to_compress).write_text("This is a test file to be compressed with Zstandard.\n")
try:
# 1. Create a Zstandard compressed ZIP archive
print(f"Creating {archive_name} with Zstandard compression...")
with zipfile.ZipFile(archive_name, 'w', compression=ZIP_ZSTANDARD) as zf:
zf.write(file_to_compress)
print(f"Successfully created {archive_name}.")
# 2. Read and extract from the Zstandard compressed ZIP archive
print(f"Extracting from {archive_name}...")
os.makedirs(extracted_dir, exist_ok=True)
with zipfile.ZipFile(archive_name, 'r') as zf:
zf.extractall(extracted_dir)
print(f"Content extracted to {extracted_dir}.")
# Verify content
extracted_file_path = Path(extracted_dir) / file_to_compress
if extracted_file_path.exists():
print(f"Extracted content: {extracted_file_path.read_text().strip()}")
else:
print("Extraction failed or file not found.")
finally:
# Clean up created files and directories
if Path(file_to_compress).exists():
os.remove(file_to_compress)
if Path(archive_name).exists():
os.remove(archive_name)
if Path(extracted_dir).exists():
import shutil
shutil.rmtree(extracted_dir)
print("Cleanup complete.")
Debug
Known issues
breakingPython 3.14 and newer versions include native Zstandard support in the standard `zipfile` module (via `compression.zstd` and the `zipfile.ZIP_ZSTANDARD` constant). This `zipfile-zstd` package is intended for compatibility with older Python versions (<3.14). Using it on Python 3.14+ might lead to conflicts or be unnecessary.fixFor Python 3.14+, prefer the native `zipfile.ZIP_ZSTANDARD` and `compression.zstd` module. For older versions, continue using `zipfile-zstd`.
affects: >=3.14 (CPython)
gotchaThe `zipfile-zstd` library does not support advanced Zstandard compression parameters or dictionaries, which are available in the underlying `python-zstandard` library. It offers only basic Zstandard compression levels.fixFor basic Zstandard compression, `zipfile-zstd` is sufficient. For advanced features (like dictionaries or finer control over parameters), use `python-zstandard` directly for compression and then integrate it manually if creating a custom ZIP structure, or consider if Python's native 3.14+ `zipfile` module offers more options.
affects: <0.0.4
gotchaZIP archives compressed with Zstandard (method ID 93) may not be universally compatible with all ZIP tools, especially older ones (e.g., some versions of Windows Explorer or 7-Zip might require specific forks or updates to handle Zstandard compressed ZIPs).fixVerify compatibility with target systems' ZIP utilities if cross-platform or older tool compatibility is critical. Consider using more widely supported compression methods like Deflate if universal compatibility is a higher priority.
affects: All versions
gotchaAttempting very high Zstandard compression levels (e.g., 20 or higher) within a ZIP context can lead to 'Out of memory' errors, even for small files, depending on the underlying Zstandard implementation and available system resources.fixIf encountering out-of-memory errors, reduce the Zstandard compression level. Levels typically between 3-9 offer a good balance of compression ratio and speed for most use cases without excessive memory usage.
affects: All versions
Upgrade
Version history
0.0.4latest on PyPI · released Dec 8, 2021
Audit
Dependencies
python-zstandardrequiredProvides Python bindings for the Zstandard compression library, which is required by zipfile-zstd for Zstandard support.