Skip to main content

ziptensors

Lossless, compressed containers for tensor files (safetensors, GGUF, ONNX, PyTorch zip and opaque files) with random access at tensor speed. Every restored file is bit-exact and proven by its BLAKE3 hash. This is the Python module of ziptensors; the command line tool and the Rust library live in the same repository.

Install

pip install ziptensors            # the module
pip install "ziptensors[torch]"   # with the PyTorch loader's dependency

Wheels are abi3 for CPython 3.11 and later on Linux (x86_64, aarch64), Windows (x64) and macOS. Other platforms build from the source distribution, which needs a Rust toolchain and a C compiler.

Write

import ziptensors

report = ziptensors.encode_file("model.safetensors", "model.ziptensors")  # one file
print(report.output_len, report.total.stored)

# Several files; a (path, member name) pair names the member, a bare path uses the file name.
inputs = ["unet.safetensors", ("downloads/vae.safetensors", "vae/model.safetensors")]
ziptensors.pack(inputs, "pipeline.ziptensors")

mode is fast, balanced (the default of encode_file) or max (the default of pack). A new file is decoded and compared with its source before it replaces anything at the output path. A directory given to pack is walked: its files are named relative to it, and symbolic links and *.incomplete downloads are skipped (ziptensors.collect_inputs shows what a walk takes). ziptensors.PackBuilder adds members one by one and is a context manager: leaving it without finish() leaves nothing behind.

Edit, recover, whole trees

from ziptensors import AddOp, RemoveOp, ReplaceOp

ziptensors.edit("pipeline.ziptensors", [AddOp("lora.safetensors"), RemoveOp("old.safetensors")])
ziptensors.edit("pipeline.ziptensors", [ReplaceOp("vae/model.safetensors", "vae2.safetensors")],
                strategy="append")       # writes only the new data after the end
ziptensors.compact("pipeline.ziptensors")  # drops what earlier appends left behind
ziptensors.recover("pipeline.ziptensors")  # after an interrupted append: back to the last valid state

report = ziptensors.compress_tree("models/")   # each weight file becomes a .ziptensors beside it
ziptensors.decompress_tree("models/")          # and back, bit-exact

edit proves the result before it replaces anything. strategy="in_place" needs no extra disk space but is risky: an interruption damages the file, so keep a backup. A tree run reports one outcome per file and goes on past a failure; check report.has_failures. ziptensors.enable_stderr_logging("info") shows the library's progress and errors on stderr.

Read

import ziptensors

container = ziptensors.Container("model.ziptensors", max_total_decoded=64 << 30)
member = container.member()                      # the only member; or container.member("name")
head = member.read(0, 4096)
for tensor in member.tensors:
    print(tensor.name, tensor.dtype, tensor.shape)
member.restore_file("model.safetensors")         # bit-exact copy of the original

Member.read_at(offset, buffer), Member.read_many([(offset, buffer), ...]) and Member.decode_tensor_into(name, buffer) fill any writable buffer (a bytearray, a numpy array) with the GIL released. Member.open() returns a seekable read-only file, for example for torch.load. Container is a context manager, container.restore_all("dir") restores every member, and container.layer_report() tells where the bytes went.

Untrusted input: max_total_decoded has no default limit. Set it whenever a container comes from somewhere else. The hashes detect damage; they do not authenticate a file.

PyTorch

import torch
from ziptensors.torch import load_state_dict

state = load_state_dict(container.member(), device="cuda", dtype=torch.float16)

Tensors are decoded in place into new torch tensors; on a CUDA or ROCm device the copy overlaps with decoding through pinned staging buffers. ziptensors.torch.load_into(module, member) fills a module built on the meta device. GGUF block-quantized tensors are refused by default; quantized="raw" or quantized="diffusers" hands them over undecoded.

safetensors API

from ziptensors.safetensors import safe_open

with safe_open("model.ziptensors", framework="pt", device="cpu") as f:
    for key in f.keys():
        tensor = f.get_tensor(key)
    rows = f.get_slice("embed.weight")[0:16]

safe_open reads a safetensors member the way safetensors.safe_open reads a file, with the frameworks pt and np.

Mount (Linux and Windows)

from diffusers import StableDiffusionPipeline

with ziptensors.mount("pipeline.ziptensors", "/mnt/sd15") as mounted:
    pipe = StableDiffusionPipeline.from_pretrained(mounted.mountpoint)   # any program that takes a path

with ziptensors.mount_overlay("models/", "/mnt/models"):   # a compress_tree tree, originals restored
    ...

Every member shows as a read-only file; an overlay shows each per-file container as its original file and every other file as it is. Leaving the with block unmounts, also after an exception or Ctrl-C; close files opened under the mount first, since the unmount waits for them. Linux needs /dev/fuse and fusermount3 (package fuse3), no root; the mount point is an existing directory. Windows needs WinFsp, installed from https://winfsp.dev/rel/; the mount point is a free drive letter (X:) or a directory that does not exist yet. macOS has no mount: the calls raise ziptensors.MountError.

WinFsp - Windows File System Proxy, Copyright (C) Bill Zissimopoulos, https://github.com/winfsp/winfsp. ziptensors uses the WinFsp DLL under its FLOSS exception and distributes no WinFsp file.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Metadata

Release files for ziptensors 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ziptensors 0.2.0
File Size Uploaded Provenance Actions
ziptensors-0.2.0.tar.gz 682.3 kB With provenance Details for ziptensors-0.2.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for ziptensors 0.2.0
File Actions
ziptensors-0.2.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for ziptensors-0.2.0-cp311-abi3-win_amd64.whl
ziptensors-0.2.0-cp311-abi3-manylinux_2_28_x86_64.whl CPython 3.11 abi3 Linux glibc 2.28+ x86-64 Details for ziptensors-0.2.0-cp311-abi3-manylinux_2_28_x86_64.whl
ziptensors-0.2.0-cp311-abi3-manylinux_2_28_aarch64.whl CPython 3.11 abi3 Linux glibc 2.28+ ARM64 Details for ziptensors-0.2.0-cp311-abi3-manylinux_2_28_aarch64.whl
ziptensors-0.2.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for ziptensors-0.2.0-cp311-abi3-macosx_11_0_arm64.whl
ziptensors-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for ziptensors-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 7.1 MB

Release files / ziptensors-0.2.0.tar.gz

Download URL ziptensors-0.2.0.tar.gz
Size 682.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4153a3a348fecc83df8846e18339281388c5a0efda6d664b5d781a86342b57ce
BLAKE2b-256 checksum
How to use checksums
7c3046b869c80f3fb5c0bd1b2239752911b9c7eb7612c95f8eaa55380756e333
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / ziptensors-0.2.0-cp311-abi3-win_amd64.whl

Download URL ziptensors-0.2.0-cp311-abi3-win_amd64.whl
Size 1.2 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
62c4c6cf5c24a8695b5f210fb4dd514c100160c6311ca611ed9db988dad5e956
BLAKE2b-256 checksum
How to use checksums
0050576164f924f29f581eb55b261ba7e45f83ad2f932dec2672446ec3e187ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / ziptensors-0.2.0-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL ziptensors-0.2.0-cp311-abi3-manylinux_2_28_x86_64.whl
Size 1.5 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
2996cf79e22ab5c214b86a49cb42869d158dd41e0b76b00c66e187b64102e6a4
BLAKE2b-256 checksum
How to use checksums
bec4ebe6df35a77549ace1d927ab32c4ea980d388221a3eb90f5ef307f68a86c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / ziptensors-0.2.0-cp311-abi3-manylinux_2_28_aarch64.whl

Download URL ziptensors-0.2.0-cp311-abi3-manylinux_2_28_aarch64.whl
Size 1.5 MB
Tags CPython 3.11 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
b8e84d07ceaf1f348d23789cf7f2147b65a7088eace74fbc4af51162f3f23871
BLAKE2b-256 checksum
How to use checksums
ba2b38ede101aefe7158e4ae0df55cc1ba83e962d7711fba601fb71b3b44c97a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / ziptensors-0.2.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL ziptensors-0.2.0-cp311-abi3-macosx_11_0_arm64.whl
Size 1.1 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ed2a8ebc2cd7469492dc5ece766e90e406d202f09dd43cf7d4246ec8f264023c
BLAKE2b-256 checksum
How to use checksums
bb692be9b25d940b5a3c0b99f584ebaa011518f9d5ac382a42af36f91f0e71f8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / ziptensors-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl

Download URL ziptensors-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl
Size 1.2 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
4d1a3f2c31ecd81e692fc66f60d9c147e785d0ef4a15cff1cf312eea5b8fe19d
BLAKE2b-256 checksum
How to use checksums
f64103cb67ce890a778e4181585c4d2c77ce30ea32f9f74532dc0d5f1b387ae0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for ziptensors 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for ziptensors-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

6 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page