Ballerina Zip Library

August 18, 2026 · View on GitHub

Overview

The zip library provides APIs to create and read ZIP archives from Ballerina.

A file or a directory is archived with compress and unpacked with decompress, and what an archive holds can be listed with listEntries without unpacking it. For finer control, ArchiveWriter builds an archive entry by entry and ArchiveReader reads one entry at a time; both take and return content as byte streams, so an archive never has to be held in memory. An entry can also be moved between archives with copyEntry, which carries the stored bytes across without decompressing them.

An archive that arrives from outside a system is read defensively. An entry whose name would write outside the target directory, a symbolic link, and an entry that is encrypted or stored with a compression method the library does not support are each refused with their own error type. ExtractionLimits caps the number of entries, the total uncompressed size, and how far a single entry may expand beyond the size it stores, so an archive built to exhaust the disk is stopped rather than unpacked.

Quickstart

To use the zip library in your Ballerina application, update the .bal file as follows.

Step 1: Import the module

import ballerina/io;
import ballerina/zip;

Step 2: Archive and unpack

The limits cap what an archive is allowed to expand to, so one built to exhaust the disk is stopped rather than unpacked.

public function main() returns error? {
    check zip:compress("./reports", "./reports.zip");

    zip:Entry[] entries = check zip:listEntries("./reports.zip");
    foreach zip:Entry entry in entries {
        io:println(entry.name, " ", entry.uncompressedSize);
    }

    check zip:decompress("./reports.zip", "./restored", {
        limits: {maxEntries: 1000, maxTotalSize: 100 * 1024 * 1024}
    });
}

Step 3: Work entry by entry

Use ArchiveWriter and ArchiveReader when the archive is assembled from more than one source, or when only a part of it is needed.

zip:ArchiveWriter writer = check new ("./bundle.zip", {level: zip:BEST});
check writer.addFile("./summary.pdf");
check writer.addEntry("notes.txt", "shipped on 2026-08-16".toBytes());
check writer.close();

zip:ArchiveReader archive = check new ("./bundle.zip");
byte[] notes = check archive.readEntry("notes.txt");
check archive.close();

Step 4: Run the Ballerina application

bal run

Examples

The zip library provides practical examples illustrating usage in various scenarios. Explore these examples.

Unpack an Untrusted Archive: Unpacks an archive that came from outside the system. Caps what the extraction is allowed to cost with ExtractionLimits, and tells a hostile archive from a broken one by the error type it gets back.
Rewrite an Archive: Adds an entry to and removes an entry from an archive, which a ZIP cannot do in place. Carries the entries that stay across with copyEntry, exactly as they are stored.

Build from the source

Setting up the prerequisites

Download and install Java SE Development Kit (JDK) version 21. You can download it from either of the following sources:
- Oracle JDK
- OpenJDK
Note: After installation, remember to set the JAVA_HOME environment variable to the directory where JDK was installed.
Download and install Ballerina Swan Lake.
Export a GitHub personal access token with read package permissions as follows:
```
export packageUser=<Username>
export packagePAT=<Personal access token>
```

Build options

Execute the commands below to build from the source.

To build the package:
```
./gradlew clean build
```
To run the tests:
```
./gradlew clean test
```
To build without the tests:
```
./gradlew clean build -x test
```

To run tests against different environments:

./gradlew clean test -Pgroups=<Comma separated groups/test cases>

To debug the package with a remote debugger:
```
./gradlew clean build -Pdebug=<port>
```

To debug with the Ballerina language:

./gradlew clean build -PbalJavaDebug=<port>

Publish the generated artifacts to the local Ballerina Central repository:
```
./gradlew clean build -PpublishToLocalCentral=true
```
Publish the generated artifacts to the Ballerina Central repository:
```
./gradlew clean build -PpublishToCentral=true
```

For example demonstrations of the usage, go to Ballerina By Examples.
Chat live with us via our Discord server.
Post all technical questions on Stack Overflow with the #ballerina tag.