When we work with archives and compressed files, we usually want a tool that is both efficient and dependable. Today I want to introduce an exciting new Python project: tzst. It is a next-generation archive management library built for Python 3.12+, designed around the modern Zstandard (zstd) compression algorithm to deliver strong performance, solid security, and production-grade reliability.

codecov CodeQL CI/CD PyPI - Version PyPI - Downloads GitHub License Sponsor

If you are tired of the performance limits or security concerns of traditional archiving tools, or you are looking for a modern archive solution for your Python project, tzst is absolutely worth a close look.

1. Core Features of tzst

tzst is much more than a basic compression tool. It comes with a carefully designed feature set that helps it stand out:

  • Efficient compression: Built on Zstandard, tzst delivers excellent compression ratios together with impressive compression and decompression speed. You save both storage space and time.
  • Tar compatibility: It creates standard tar archives compressed with Zstandard (.tar.zst) for broad compatibility, while also supporting the custom .tzst extension.
  • Powerful CLI: The command-line interface is intuitive and feature-rich, with streaming support, verbose output, compression-level control, and more for daily use and scripting.
  • Clean Python API: In addition to the CLI, tzst provides a Pythonic API that makes archive capabilities easy to integrate into your own applications.
  • Cross-platform support: Windows, macOS, and Linux all get a consistent experience.
  • Memory efficiency: A dedicated streaming mode keeps memory usage low when working with large archives, which is especially helpful on constrained systems or with huge datasets.
  • Atomic operations: Archive creation uses atomic file operations by default. Archives are built as temporary files first and moved into place only after success, preventing broken or partial output after crashes or power loss.
  • Secure by default: During extraction, tzst uses the data safety filter by default. This blocks dangerous members such as absolute paths, path traversal attempts like ../../.., and risky file types such as device files or links that escape the destination.
  • Better error handling: Errors are clear and actionable, with helpful hints whenever possible.

2. Installation and Quick Start

Installing tzst is straightforward. You can choose the option that fits your workflow best.

2.1 Install from PyPI

For most Python users, this is the easiest option:

pip install tzst

2.2 Download a standalone executable from GitHub Releases

If you want to use the tzst CLI on a machine without Python, or you do not want to install Python dependencies, you can download a prebuilt standalone executable from the project’s GitHub Releases page. Builds are available for Linux (x86_64, ARM64), Windows (x64, ARM64), and macOS (Intel and Apple Silicon).

2.3 Install from source

If you want the latest code or plan to contribute:

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install .
# Or install in editable mode for development
pip install -e .[dev]

2.4 Quick Start Examples

2.4.1 Command line usage

Note: The standalone binaries provide the best performance and do not require Python. You can also run tzst without installing it via uvx tzst. See the uv documentation.

# Create an archive containing file1.txt, file2.txt, and directory/
tzst a my_archive.tzst file1.txt file2.txt directory/

# Extract everything from my_archive.tzst into the current directory
tzst x my_archive.tzst

# List archive contents
tzst l my_archive.tzst

# Test archive integrity
tzst t my_archive.tzst

2.4.2 Python API usage

from tzst import create_archive, extract_archive, list_archive, test_archive

# Files and directories to archive
files_to_archive = ["file1.txt", "file2.txt", "directory/"]
archive_path = "my_api_archive.tzst"
extract_to_path = "extracted_content/"

# Create archive
create_archive(archive_path, files_to_archive, compression_level=5)
print(f"Archive '{archive_path}' created successfully.")

# List archive contents
print(f"\nContents of '{archive_path}':")
contents = list_archive(archive_path, verbose=True)
for item in contents:
    print(
        f"- {item['name']} (size: {item['size']} bytes, type: {'file' if item['is_file'] else 'directory'})"
    )

# Test archive integrity
if test_archive(archive_path):
    print(f"\nArchive '{archive_path}' passed the integrity test.")
else:
    print(f"\nArchive '{archive_path}' is corrupted!")

# Extract archive
extract_archive(archive_path, extract_to_path)
print(f"\nArchive extracted to '{extract_to_path}'.")

3. Why Choose tzst?

  • Modern Python support: Built specifically for Python 3.12+ and designed to take advantage of modern Python features.
  • The power of Zstandard: Zstandard offers better compression ratios than traditional gzip and faster decompression, while usually also compressing faster than xz.
  • Security and reliability: The default safety filter and atomic operations add an extra layer of protection for your data.
  • Ease of use: Both the CLI and the Python API are intentionally straightforward and pleasant to use.

4. Digging Deeper

The README.md and the project documentation cover advanced topics in more detail, including the effect of different compression levels, the details of streaming mode, and the available safety filters: data, tar, and fully_trusted.

For example, tzst’s streaming mode is very useful when working with archive files in the gigabyte or even terabyte range, because it avoids loading the entire archive into memory. In the CLI, you can enable it with --streaming. In the Python API, pass streaming=True when initializing TzstArchive.

5. Contributing and Support

tzst is open source, and contributions from the community are welcome. If you hit an issue or have feature suggestions, please open an issue on GitHub. If you want to contribute code, documentation, or testing help, check the project’s CONTRIBUTING.md.

Closing Thoughts

For Python developers who care about efficiency, security, and a modern workflow, tzst is an excellent archiving solution. With strong Zstandard integration, a capable feature set, and a developer-friendly CLI and API, it has the potential to become a very handy tool in your toolbox.

Start with pip install tzst and see how much smoother your archive workflows can become.