---
id: zlib-state
version: "0.1.12"
license: unclear
license_treatment: permissive
maintenance: active
---

# zlib-state — Low-level interface to the zlib library that enables capturing the decoding state

License: permissive · Maintenance: active · Downloads: 221.5K/mo

## What it is and what it does

zlib-state wraps the zlib library to expose decompression state at deflate block boundaries, allowing you to pause and resume gzip decompression from a known position. It provides two main interfaces: Decompressor for fine-grained control over the decompression stream, and GzipStateFile for a file-like reader that tracks state after each block. The package trades some simplicity for the ability to checkpoint progress mid-file, which is useful when processing large compressed files where you need to pause, save position, and resume later.

The library is a thin binding over zlib's internal state machine and requires careful use—decompression can only resume at block boundaries, not arbitrary byte positions. It has no runtime dependencies and is distributed as precompiled wheels for modern Python versions on Linux and Windows, making installation straightforward on supported platforms.

Use it for:

- Pause and resume decompression of large gzip files across application restarts or crashes.
- Implement checkpointing in data pipelines that process compressed logs or archives incrementally.
- Build fault-tolerant streaming decompressors that can recover from interruption at known block boundaries.
- Optimize gzip iteration performance when standard library decompression is a bottleneck.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides low-level access to zlib decompression with the ability to capture and restore decoder state at block boundaries, enabling resumable gzip file reading.

Yes, if you need to checkpoint gzip decompression progress or require faster iteration over compressed streams. The permissive MIT license and active maintenance make it low-risk. Not necessary if you only need standard gzip reading or cannot work within the block-boundary constraint.

## Install

pip install zlib-state
uv add zlib-state
poetry add zlib-state

## Installing zlib-state

Before you install: Medium install friction due to compiled wheels; prebuilt binaries available for Python 3.9–3.14 on Linux and Windows. Active maintenance with recent release.

License in practice: MIT license (permissive); no restrictions on commercial or private use.

Quickstart:

import zlib_state

# Capture state at block boundary
decomp = zlib_state.Decompressor(32 + 15)
with open('file.gz', 'rb') as f:
    while not decomp.eof():
        if decomp.needs_input() > 0:
            decomp.feed_input(f.read())
        decomp.read()
        if decomp.block_boundary():
            state = decomp.get_state()
            pos = decomp.total_in()
            break

Requires Python 3.9 or later; state capture only works at deflate block boundaries, not arbitrary file positions.

Verify before relying:

- Whether performance advantage over standard gzip holds across different file sizes and compression levels.
- Compatibility with all gzip variants and edge cases (e.g., concatenated gzip streams).
- Memory overhead of storing state objects for large files.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 221.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

gzip decompression state capture, resumable gzip file reading, zlib state management, deflate block boundaries, streaming gzip decompression, zlib decoder state, partial gzip decompression, compression, streaming, checkpointing

[View on SkillFed](https://skillfed.io/packages/zlib-state) · [View on PyPI](https://pypi.org/project/zlib-state/)