madler/zlib: the deflate library most software already links against

What zlib actually is, and who ends up using it

zlib is a general purpose data compression library written in C. The README describes it as implementing the data format specified by RFC 1950 (zlib), RFC 1951 (deflate) and RFC 1952 (gzip). Those three RFCs are the whole product surface: if your problem is "produce or consume a gzip stream" or "store bytes in a zlib wrapper", zlib is the reference implementation rather than one of several options.

The audience is narrower than the download numbers suggest. You are the right reader if you are writing C or C++ and need to compress a buffer, wrap a file descriptor in gzip, or decode a stream someone else produced. You are also the right reader if you are writing in another language and want to know what sits underneath your standard library's compression module. The README lists several of those bindings directly: java.util.zip in Java, IO-Compress for Perl, the zlib module in Python from version 1.5 onward, and a built-in zlib in Tcl. In those cases you are not adopting zlib, you are already running it.

The library is also not a file format tool. The README points to contrib/minizip for reading and writing .zip files and explicitly calls that package experimental. If your requirement is "open this .zip archive", that is the entry point the project offers, and it comes with the label the project put on it.

The deflate window, the zlib wrapper and the gzip wrapper

The mechanism is a sliding window LZ77 match finder feeding a Huffman coder, which is what RFC 1951 defines. The library exposes it through three layers of API rather than one. The raw deflate functions emit a bare compressed stream with no header and no checksum. The zlib functions add the RFC 1950 header and an Adler-32 checksum, computed in adler32.c. The gzip functions add the RFC 1952 header and a CRC-32, computed in crc32.c. The repository layout makes this concrete: deflate.c and inflate.c are the codec, inflate.c has a separate infback.c for the callback-driven streaming case, and gzlib.c, gzread.c, gzwrite.c and gzclose.c implement the gzFile layer that reads and writes gzip files.

That split matters when you pick an entry point. gzFile is the file-oriented interface and is the closest thing to a drop-in for stdio. The z_stream interface is the in-memory one and is what you use when the data is a buffer, a socket or a database column rather than a path. infback.c exists for callers that want inflate to pull input through a callback instead of being handed a buffer.

The README states that all the code is thread safe, with a caveat it defers to the FAQ rather than spelling out here. That is a real limit on what this page can tell you: the threading contract is documented in the FAQ file in the repository, not in the README, so the README alone is not enough to reason about concurrent use.

Building zlib from source on Unix and Windows

The README gives the Unix path directly: follow the instructions at the top of Makefile.in, which in short are ./configure, then make test, then make install. The top-level Makefile is deliberately not the build entry point. It contains one rule that prints "Please use ./configure first. Thank you." and a distclean target that delegates to Makefile.in. Running make without configuring is meant to fail with that message.

The three commands, in the order the README gives them:

./configure
make test
make install

make test is not optional in practice. The README's target notes describe several compilers and platforms where the build succeeds but the library misbehaves: 64-bit Irix needs deflate.c compiled without optimization because a libpng test fails with -O, Digital Unix 4.0D on AlphaServer needs cc option -std1 for gzprintf to work (configure adds it), and HP-UX 9.05 fails with some versions of /bin/cc but works with others. The README says to use make test to check your compiler. That is the project telling you the test suite is the compatibility gate.

On Windows the path is different. The README points at the special makefiles in win32/ or contrib/vstudio/, and at win32/DLL_FAQ.txt for DLL versions. There is also a CMake build: CMakeLists.txt, README-cmake.md, zlibConfig.cmake.in and zlib.pc.cmakein are all present at the top level, and BUILD.bazel and MODULE.bazel exist for Bazel consumers. The README does not walk through either of those, so README-cmake.md is where you would look for the CMake route. For VMS the repository ships make_vms.com, and there are directories for amiga, msdos, os400, qnx and watcom.

What you should see after a successful make test is the test programs in test/ completing, including test/example.c, which the README describes as both a usage example and a correctness test, and test/minigzip.c, a second example.

A first real use: reading the only API reference there is

There are no man pages. The README says all functions of the compression library are documented in zlib.h and asks for volunteers to write man pages, contacting [email protected]. The repository does ship zlib.3 and zlib.3.pdf, but the README's own pointer for function documentation is the header. So the first real task after installing is opening zlib.h, not running a tutorial.

The README names two worked examples rather than reproducing them. test/example.c is described as a usage example that also tests the library, and test/minigzip.c is a second example. Those two files in test/ are where the README sends you for a working call sequence, and zlib.h is where the parameter meanings live. Read them together: the example shows the order of calls, the header explains what each argument means and what the return value signals.

If you are on CMake rather than the autoconf path, README-cmake.md is the file to read before writing your own find_package call, because zlibConfig.cmake.in is what gets installed as the package config, and zlib.pc.in and zlib.pc.cmakein are the pkg-config templates the repository ships for the same purpose.

Where zlib is the wrong tool

zlib gives you one algorithm family. If your actual requirement is the smallest file at any CPU cost, deflate is not the answer, and zlib does not pretend otherwise. Its compression levels are a dial within deflate, not a choice of codec, and the README documents no alternative backend. The FAQ in the repository is where level selection is discussed; the README does not discuss it at all.

The .zip case is the second boundary. The README describes contrib/minizip as an experimental package, written by Gilles Vollant, to read and write .zip files on top of zlib. Experimental is the project's word. If you need archive semantics (multiple members, central directory, per-entry metadata), you are building on a component the maintainers do not present as finished.

The third boundary is documentation depth. Function-level documentation lives in zlib.h. The README does not document error handling strategy, does not document a rollback or recovery path for partially written gzip files, and does not describe the threading caveats it defers to the FAQ. For a library this widely deployed that is a deliberate minimalism, but it means a team that needs prose documentation has to budget for reading headers and the FAQ file.

Finally, portability is not free. The README's target notes are a list of platforms where the build needs special handling, including a compiler bug reported to SGI for 64-bit Irix. If you support an unusual toolchain, the test suite is the only signal the README offers.

zlib against zstd, and against your language's standard library

The comparison people actually search for is zlib versus zstd. The difference in approach is format compatibility against ratio. Deflate is defined by RFC 1951 and is understood by essentially every HTTP stack, archive tool and runtime, which is why zlib's output is safe to hand to a system you do not control. zstd is a different format with its own frame definition; the README of this repository does not mention it, does not provide a zstd backend, and does not offer a compatibility shim. Choosing zstd is choosing a different wire format, not a different setting on the same one. If the receiving end is not yours, that choice is usually made for you.

The second alternative is not a competing library at all. For Python, Java, Perl and Tcl, the README states that zlib is already available through the standard library (the Python zlib module, java.util.zip, IO-Compress, and zlib built into Tcl). In those languages, adding a dependency to get deflate is unnecessary work. The reason to go to madler/zlib directly is that you are in C or C++, or you need the gzFile layer or the streaming z_stream interface at a level your binding does not expose.

A third option worth naming is the CMake and Bazel entry points in this same repository. If your build is CMake-based, using CMakeLists.txt and README-cmake.md keeps you on the upstream source with the upstream ChangeLog, rather than on a distribution repackage whose patches you would have to track separately.

Licence, maintenance and what an upgrade costs you

The repository's LICENSE is the zlib licence, reproduced in the README as a three-clause permission notice with an as-is warranty disclaimer. It permits use for any purpose including commercial applications, alteration and redistribution. Three conditions apply: you must not misrepresent the origin or claim you wrote the original, altered source versions must be plainly marked as altered and not presented as the original, and the notice may not be removed or altered from any source distribution. The authors also state that the library was written entirely by Jean-loup Gailly and Mark Adler, includes no third-party code, and that they make contributions in a personal capacity. If you redistribute modified sources, the README asks that you record your changes in ChangeLog history. This is a permissive licence with attribution and marking obligations rather than copyleft; it is not legal advice and the exact obligations for your distribution are for your own counsel.

Maintenance is active. The last push to the develop branch was on 2026-09-21, and the repository is not archived. Release cadence is slow and irregular by design: v1.3 on 2023-08-18, v1.3.1 on 2024-01-22, v1.3.2 on 2026-02-17. The README refers to the version as 1.3.2.1 and says the changes in 1.3.2.1 are documented in ChangeLog, while the most recent tagged release in the list is v1.3.2. That gap between the README's version string and the newest tag is the thing to check before you decide which revision you are tracking.

Upgrade cost is low in the usual case and non-zero in the unusual one. The API surface is zlib.h, which is stable enough that the README's own examples are decades old and still shipped. The cost concentrates in the platforms the target notes describe, where a new version can reintroduce a compiler-specific failure that make test will catch and nothing else will.

Editorial conclusion

Adopt zlib when you need to read or write deflate, zlib or gzip streams from C, or when you need a compression format that every other runtime already understands. Do not adopt it as a general archiver: the README points at contrib/minizip for .zip support and calls that package experimental, and it does not offer a modern high-ratio codec. Before you commit, read zlib.h rather than expecting man pages, run make test on your target compiler because the README records several compiler-specific failures, and check the ChangeLog for what 1.3.2.1 changed.

Frequently asked questions

Official sources

1. Issues
2. madler/zlib on GitHub
3. Project website
4. README
5. Releases