zipstream-ng

library1.9.2pypypi✓ verified 84d ago

Zipstream-NG is a modern and easy-to-use Python library for generating streamable ZIP files on the fly. It allows packaging and streaming many files and folders without requiring temporary files or excessive memory, making it ideal for web backends. It also supports calculating the final ZIP file size before generation, enabling accurate Content-Length headers for HTTP responses. The current version is 1.9.0, and it maintains an active release cadence.

serialization

pip install zipstream-ng

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · ZIPSTREAM-NG

zipstream-ng

serializationpythonv1.9.2

Install

1.5s avg

Import

44ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.9.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.046s · 17.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.043s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ZipStream

✓ from zipstream import ZipStream

✗ from zipstream_ng import ZipStream

The package is installed as 'zipstream-ng' but the main class 'ZipStream' is imported directly from the 'zipstream' module. Importing from 'zipstream_ng' will fail, and there's an older, separate library called 'zipstream' that is not `zipstream-ng` and may lead to unexpected behavior if imported by mistake.

This example demonstrates how to create a ZipStream from a local directory path and then iterate over its chunks to write the streamed ZIP content to a new file. This pattern is easily adaptable for streaming over an HTTP response or other byte sinks.

from zipstream import ZipStream import os # Create a dummy directory and files for the example if not os.path.exists('my_files'): os.makedirs('my_files') with open('my_files/file1.txt', 'w') as f: f.write('This is file one.') with open('my_files/file2.txt', 'w') as f: f.write('This is file two.') # Stream files from a directory into a zip file output_filename = 'archive.zip' zs = ZipStream.from_path('my_files') # To save to a local file: with open(output_filename, 'wb') as f: for chunk in zs: f.write(chunk) print(f'Successfully created {output_filename} containing files from my_files/') # Clean up dummy files os.remove('my_files/file1.txt') os.remove('my_files/file2.txt') os.rmdir('my_files')

Debug

Known issues

gotchaConfusing Package Name vs. Import Path: The library is installed via `pip install zipstream-ng` but the primary class is imported as `from zipstream import ZipStream`. There is an older, unrelated `zipstream` package on PyPI which is no longer maintained. Ensure you are importing `ZipStream` from the correct module (`zipstream`) after installing `zipstream-ng`.

fix

Always use `from zipstream import ZipStream` after installing `zipstream-ng`. Verify the correct package is installed with `pip show zipstream-ng`.

affects: All versions

gotchaPotential for Corrupt Zips in Web Streaming: When streaming ZIPs over HTTP, incorrect handling of HTTP headers (e.g., `Content-Length`, `Content-Disposition`) or premature termination of the stream can lead to corrupt downloads. `zipstream-ng` can pre-calculate the size (if no compression is used), which is crucial for `Content-Length`.

fix

For web applications, ensure you set `Content-Type: application/zip`, `Content-Disposition: attachment; filename="your_file.zip"`, and, if possible, `Content-Length` using `len(zs)` (where `zs` is your ZipStream instance without compression). Ensure the entire generator is consumed and sent to the client.

affects: All versions

gotchaEncoding of String Data: When adding string data directly to the ZipStream (rather than files), ensure it's explicitly encoded to bytes (e.g., `my_string.encode('utf-8')`). Passing unencoded strings or incorrectly encoded bytes can lead to corrupted file contents within the ZIP archive.

fix

Always encode string data to bytes before adding it to `ZipStream`. For example: `zs.add(my_string.encode('utf-8'), 'text_file.txt')`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'zipstream_ng'

The `zipstream-ng` package is not installed in the current Python environment or the import name is incorrect.

fix

Install the package using pip: `pip install zipstream-ng`

TypeError: data must be bytes or a file-like object, got <class 'str'>

The `data` argument passed to the `add()` method or specified in a `FileEntry` dictionary is a string instead of bytes or a file-like object.

fix

Encode the string to bytes (e.g., UTF-8) before passing it as data: `zip_stream.add('file.txt', 'hello'.encode('utf-8'))`

TypeError: 'AioZipStream' object is not an iterator

An `AioZipStream` instance, which is an asynchronous iterator, is being incorrectly used with a synchronous `for` loop.

fix

Use an `async for` loop to consume the asynchronous stream within an `async` function: `async for chunk in aio_zip_stream: ...`

AttributeError: 'ZipStream' object has no attribute 'read'

The `ZipStream` object is an iterable that yields chunks of the ZIP file; it does not have a `read()` method like a traditional file-like object.

fix

Iterate over the `ZipStream` object to get the chunks of the ZIP file: `for chunk in zip_stream: ...` or `content = b''.join(zip_stream)`

Upgrade

Version history

1.9.2latest on PyPI · released May 17, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.5.0 or higher.

Agent activity

35 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pR0Ps/zipstream-ng ↗

packagehttps://pypi.org/project/zipstream-ng/ ↗

changeloghttps://github.com/pR0Ps/zipstream-ng/blob/master/CHANGELOG.md ↗