# QuaZip: reading and writing ZIP archives through Qt's QIODevice

> QuaZip is a C++ wrapper around Gilles Vollant's minizip that exposes ZIP archives through the Qt QIODevice API, so an application can open an archive without touching the filesystem. It is mostly feature complete, ships three API levels, and the README is openly asking for more maintainers.

**stachenov/quazip** — Qt/C++ wrapper over minizip

- Repository: https://github.com/stachenov/quazip
- Stars: 698 · Forks: 251
- Language: C++
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/stachenov-quazip

## A Qt binding for an existing ZIP implementation

QuaZip is the C++ wrapper for Gilles Vollant's ZIP and UNZIP package, also known as minizip, using the Qt library. That is the whole architecture in one sentence, and it is worth being explicit about what it means.

QuaZip does not implement the ZIP format. The README says the original ZIP package is copyrighted by Gilles Vollant, with the details in the quazip/(un)zip.h files, and describes the licence as basically the zlib licence. What QuaZip adds is the Qt layer: the ability to work with an archive through QIODevice, which is the abstraction that lets a program read a ZIP from a network stream, from memory, or from a file without special cases for each.

The use case the README names is specific: if you need to write files to a ZIP archive or read files from one using the QIODevice API, QuaZip is the tool for that job. That is a narrower statement than being a compression library, and it is the right way to evaluate the project. A team that already has a working ZIP solution for files on disk has no reason to adopt this, while a team that needs device based access has a real gap it fills.

The dependencies are correspondingly narrow: zlib, and Qt6 or Qt5, with Qt6 searched first. The project is distributed under LGPL, with the full details in the COPYING file, and the copyright notice covers Sergey A. Tachenov and contributors from 2005 to 2020.

## Three API levels, and choosing between them

The usage section points at EXAMPLES.md for code examples, and it names the three API levels explicitly: the low-level QuaZip and QuaZipFile classes, the JlCompress utility functions, and the QuaCompress fluent interface.

That is a sensible progression. The low-level classes give you the archive and the file inside it, and they are what you reach for when you need control over entry names, compression or the raw stream. JlCompress is the convenience layer, the one you use when you want to compress a list of files or extract a whole directory without thinking about the archive structure. QuaCompress is the fluent interface on top, where a chain of calls reads as a pipeline rather than as a sequence of statements.

The choice matters more than it might look, because each level is a different commitment. JlCompress is the fastest way to get working code, but it is also the layer that hides the details you will need the moment a file name has an encoding problem or an entry is corrupt. The low-level classes are more work per call and more control per call.

The UTF-8 flag is settable at both the JlCompress and the QuaZip level, through JlCompress::Options::setUtf8Enabled() and QuaZip::setUtf8Enabled(), which is a hint that the two levels are meant to be used interchangeably for the same archive.

The repository layout backs up the three level structure as well. There is a quazip directory for the implementation, a qztest directory for the tests, a cmake directory for the build logic, a Doxyfile for the API documentation, and vcpkg.json and conanfile.py for the two supported package managers.

## The build options that decide what you get

CMake options are documented in a table, and several of them change the shape of the library you install.

`QUAZIP_QT_MAJOR_VERSION` specifies which major Qt version should be searched for, 6 or 5, and by default the build tries to find the most recent. `BUILD_SHARED_LIBS` builds QuaZip as a shared library and is on by default. `QUAZIP_LIB_FILE_NAME` sets the output libname, defaulting to a pattern that includes both the quazip version and the Qt version, so a Qt5 build and a Qt6 build sit side by side without clashing. `QUAZIP_INSTALL` enables installation and is on by default.

Three options deserve a closer look. `QUAZIP_BZIP2` enables BZIP2 compression and is on by default, which is why the Linux package list includes libbz2-dev. `QUAZIP_BZIP2_STDIO` routes BZIP2 errors to stdio when that compression is enabled, also on by default. And `QUAZIP_USE_QT_ZLIB` switches to Qt's bundled zlib instead of the system zlib, which the README marks as not recommended, because Qt has to be built with -qt-zlib and -static, and it is incompatible with `BUILD_SHARED_LIBS=ON`.

That incompatibility is the kind of detail that costs an afternoon if you meet it late. A shared build against Qt's bundled zlib is not a configuration that works, and the option table says so plainly.

`QUAZIP_ENABLE_TESTS` is off by default, so the test suite is opt in. `QUAZIP_ENABLE_QTEXTCODEC` is on by default and can be turned off explicitly on Qt6 even when the Core5Compat module is available, in which case the library uses QStringConverter in the background, with fewer supported encodings as the trade-off.

## Building on Linux, and the two package managers for Windows

The Linux build is short. You need the development packages, then CMake:

```bash
sudo apt-get install zlib1g-dev libbz2-dev
cmake -B build
cmake --build build
```

The full configure, build, install, test and clean cycle, with the options spelled out, is:

```bash
cmake -B build -DQUAZIP_QT_MAJOR_VERSION=6 -DBUILD_SHARED_LIBS=ON -DQUAZIP_ENABLE_TESTS=ON
cmake --build build --config Release
sudo cmake --install build
cd build
ctest --verbose -C Release
cmake --build . --target clean
```

Note that enabling the tests means ctest is part of your build loop, and the -C Release flag is how the configuration is selected for the test run.

On Windows there are two package managers, and the README is explicit that Qt is not installed as a dependency of either vcpkg or conan, so you have to provide Qt yourself. With vcpkg the steps are a preset and a build:

```bash
cmake --preset vcpkg
cmake --build build --config Release
```

With conan v2 it is a package install followed by the same pair of commands:

```bash
conan install . -of build -s build_type=Release -o *:shared=False --build=missing
cmake --preset conan
cmake --build build --config Release
```

The x86 variants use the vcpkg_x86 and conan_x86 presets, and the conan x86 line adds an architecture setting. The README notes that only Qt5 is tested on x86, which is a real constraint for anyone targeting 32-bit.

For the Qt online installer on Windows with MSVC, the instructions are to select the box for `MSVC 20XY 64-bit`, and under additional libraries select the `Qt 5 Compatibility Module`, then add the Qt directory to the PATH. If you do not use a package manager you will have to add library and include directories to the PATH or specify them with `CMAKE_PREFIX_PATH`.

## The UTF-8 flag, and why Windows behaves differently

QuaZip supports setting the UTF-8 flag on a ZIP file, through JlCompress::Options::setUtf8Enabled() or QuaZip::setUtf8Enabled(). The README explains what the flag does: it tells extractors that filenames are UTF-8 encoded.

That single bit is where ZIP portability problems live. The ZIP format predates the convention that filenames are UTF-8, and a file written without the flag can be read correctly on a Linux system and mangled on Windows, where the legacy code page is used to interpret the name. The README's behaviour summary table lays this out per platform, with Windows shown to work with the flag set and to produce mangled names, either double encoded or replaced by question marks, when the flag is absent. Linux is listed with the flag set as the working case.

The practical consequence is that if your application writes archives that other people extract on Windows, setting the flag is not optional politeness, it is a correctness requirement. The reverse also holds, since a reader that assumes UTF-8 names on an archive that was written without the flag will produce its own mangled output.

That is why the flag is exposed at both the utility and the low level. An application that only ever uses JlCompress can set it through the options object, and an application that builds archives directly can call the setter on QuaZip itself.

## LGPL terms, a 1.x migration guide and a project asking for help

Three things in the README are worth reading before you commit to the library.

The first is the licence. QuaZip is distributed under LGPL, with the full details in the COPYING file, while the original minizip package it wraps is under what the README describes as basically the zlib licence. So there are two licence layers, and a commercial application embedding QuaZip needs to satisfy the LGPL obligations for the wrapper while the underlying ZIP code is far less demanding. The LGPL nature of the wrapper is the part that needs a legal opinion for a closed source product.

The second is the migration guide. Package maintainers who want to update to QuaZip 1.0 are pointed at a dedicated migration document in the repository, and the root also holds a NEWS.txt and a RELEASE.md, so there is a written record of what changed between the 0.x and 1.x lines. That is a good sign for a library people are expected to package.

The third is the maintainer call. The README states plainly that the project is looking for additional maintainers and code reviewers, that while the library is mostly feature complete there are a couple of big ticket issues that need work, and that code review is welcome for all pull requests, pointing at a tracking issue for people versed in Qt and C and C++. The vulnerability disclosure process is covered by SECURITY.md, and the build is checked by CI and code scanning badges.

The last push to the repository was on 2026-06-30, and the recent releases are v1.7.2 on the same day, v1.7.1 on 2026-05-31 and v1.7.0 on 2026-05-26. A project that ships patch releases roughly monthly and asks for reviewers is healthy, and it is also a project where you should not expect large new features to appear on their own.

## Conclusion

Adopt QuaZip when your Qt application needs to read or write ZIP archives from a QIODevice rather than from files on disk, because that is exactly the case the wrapper exists for and it removes the platform differences in how archives are opened. Do not adopt it if you need a ZIP implementation with no Qt dependency, since the library is a Qt binding rather than a standalone archiver, and do not assume new features are being planned, since the README says the library is mostly feature complete and asks for maintainers. Verify first which Qt major version you target, since the build searches for Qt6 then Qt5 and the options table shows the switch, check whether you need BZIP2 compression enabled, which is on by default and needs libbz2-dev on Linux, and read the 1.x migration guide before upgrading, because a documented migration path exists for package maintainers.

## FAQ

### What is QuaZip?

QuaZip is the C++ wrapper for Gilles Vollant's ZIP and UNZIP package, also known as minizip, using the Qt library. It lets a C++ or Qt application read files from a ZIP archive and write files to one through the QIODevice API.

### What does QuaZip need to build?

At least zlib and either Qt6 or Qt5, with Qt6 searched first. On Linux the README installs zlib1g-dev and libbz2-dev, and BZIP2 compression is enabled by default. Windows builds use vcpkg or conan, and the README notes that Qt is not installed as a dependency of either.

### Which CMake options matter for a QuaZip build?

QUAZIP_QT_MAJOR_VERSION selects Qt 6 or Qt5, BUILD_SHARED_LIBS controls a shared or static build and defaults to ON, QUAZIP_BZIP2 enables BZIP2 compression and defaults to ON, and QUAZIP_USE_QT_ZLIB switches to Qt's bundled zlib, which the README marks as not recommended and which is incompatible with BUILD_SHARED_LIBS=ON.

### How does QuaZip handle UTF-8 file names?

QuaZip can set the UTF-8 flag on a ZIP file through JlCompress::Options::setUtf8Enabled() or QuaZip::setUtf8Enabled(), which tells extractors that filenames are UTF-8 encoded. The README's behaviour summary shows that Windows produces mangled names when the flag is not set.

## Sources

- [Issues](https://github.com/stachenov/quazip/issues)
- [README](https://github.com/stachenov/quazip/blob/master/README.md)
- [Releases](https://github.com/stachenov/quazip/releases)
- [stachenov/quazip on GitHub](https://github.com/stachenov/quazip)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stachenov-quazip