splitzip

Create split ZIP archives compatible with standard tools.

No 7-Zip required. Archives created with splitzip can be extracted using Windows Explorer, WinZip, macOS Archive Utility, and standard unzip on Linux.

Features

• Pure Python, no external dependencies
• Compatible with standard ZIP tools (no proprietary formats)
• Human-friendly size specifications ("100MB", "700MiB", "4.7GB")
• Progress callbacks for large files
• Context manager support
• CLI tool included

Installation

pip install splitzip

Quick Start

Simple Usage

import splitzip

# Create a split archive from files
splitzip.create(
    "backup.zip",
    ["documents/", "photos/", "important.pdf"],
    split_size="650MB"
)

Output files: backup.z01, backup.z02, ..., backup.zip

Context Manager

from splitzip import SplitZipWriter

with SplitZipWriter("backup.zip", split_size="100MB") as zf:
    # Add files
    zf.write("document.pdf")
    zf.write("photos/", recursive=True)
    
    # Add with custom name
    zf.write("secret.txt", arcname="data/renamed.txt")
    
    # Add content directly
    zf.writestr("hello.txt", b"Hello, World!")
    zf.writestr("config.json", '{"key": "value"}')

Advanced Options

from splitzip import SplitZipWriter, STORED, DEFLATED

def on_progress(filename, bytes_done, total_bytes):
    pct = (bytes_done / total_bytes) * 100
    print(f"\r{filename}: {pct:.1f}%", end="")

def on_volume(volume_num, path):
    print(f"Created volume: {path}")

with SplitZipWriter(
    "backup.zip",
    split_size="700MiB",          # DVD size
    compression=DEFLATED,          # or STORED for no compression
    compresslevel=9,               # 1-9 (default: 6)
    on_volume=on_volume,           # Volume creation callback
    on_progress=on_progress,       # Progress callback
) as zf:
    zf.write("large_file.bin")

Streaming from File Objects

import io
from splitzip import SplitZipWriter

data = get_data_from_somewhere()

with SplitZipWriter("archive.zip", split_size="100MB") as zf:
    zf.write_fileobj(
        io.BytesIO(data),
        arcname="streamed.bin",
        size=len(data)  # Optional, enables progress callback
    )

Size Specifications

splitzip accepts sizes in multiple formats:

Common split sizes:

• CD-ROM: "650MB" or "700MB"
• FAT32 limit: "4GiB" (minus 1 byte)
• Email attachment: "25MB"

Command Line Interface

# Create a split archive
splitzip create -o backup.zip -s 100MB file1.txt directory/

# With options
splitzip create -o backup.zip -s 700MiB \
    --level 9 \           # Max compression
    --verbose \           # Show progress
    documents/ photos/

# Store without compression
splitzip create -o backup.zip -s 100MB --store largefile.bin

Output File Naming

splitzip follows the standard ZIP split archive convention:

backup.z01  (first volume)
backup.z02  (second volume)
backup.z03  (third volume)
...
backup.zip  (final volume, contains central directory)

All files must be present in the same directory for extraction.

Compatibility

* May require all files to be selected and opened together
** May require unzip -F flag for split archives

API Reference

SplitZipWriter(path, split_size, compression=DEFLATED, compresslevel=6, on_volume=None, on_progress=None)

• path (str | Path): Path for the final .zip file.
• split_size (int | str): Maximum size per volume (bytes or human-readable string).
• compression (int): DEFLATED (default) or STORED.
• compresslevel (int): DEFLATE level 1–9 (default 6).
• on_volume ((int, Path) -> None | None): Called when a volume is created.
• on_progress ((str, int, int) -> None | None): Called with (filename, bytes_done, total_bytes).

Methods

• write(path, arcname=None, recursive=True, compression=None, compresslevel=None) — Add a file or directory. Set recursive=False to add only the directory entry without contents. Symlinks are skipped.
• writestr(arcname, data, compression=None, compresslevel=None) — Write bytes/str directly.
• write_fileobj(fileobj, arcname, size=None, compression=None, compresslevel=None) — Write from a file-like object.
• close() — Finalize the archive. Returns list of volume paths.

Exceptions

Limitations

• Minimum volume size: 64KB
• No ZIP64 support: Individual files must be under 4GB, total entries under 65,535
• No encryption: Use filesystem encryption for sensitive data
• No reading/extraction: This is a write-only library (use standard tools to extract)
• No ZSTD/LZMA: Only DEFLATE and STORED compression (for compatibility)
• Symlinks are skipped: Symbolic links are ignored with a warning

Development

# Clone and install in development mode
git clone https://github.com/twwat/splitzip
cd splitzip
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=splitzip

# Type checking
mypy src/splitzip

# Linting
ruff check src/splitzip

License

MIT License. See LICENSE for details.

Contributing

Contributions welcome! Please open an issue to discuss major changes before submitting a PR.