S3 ZIP Extension

AIStor implements an S3 extension to perform READ actions like download, list, or get metadata for individual files inside a ZIP archive stored in a bucket.

S3 requests can return information for individual files within the ZIP archive, including file size and custom headers.

To access ZIP archive contents, do the following:

1. Set the x-minio-extract header to true in your S3 requests.
2. Append the path of the content inside the archive to the path of the archive itself.

For example, to download 2025/taxes.csv archived in financial.zip and stored under a bucket named company-data, issue a GET request using the path:

company-data/financial.zip/2025/taxes.csv

The S3 ZIP extension supports the following read operations on files inside a ZIP archive:

• HeadObject
• GetObject
• ListObjectsV2

The extension does not support write operations. To update or delete contents of a file inside a ZIP archive, replace the entire ZIP archive.

When using the S3 ZIP extension, you must meet the following requirements:

• You must use ListObjectsV2 API calls to list ZIP file content.
• Use AWS key naming guidelines to ensure safe path prediction.

The following limits apply when accessing ZIP archive contents:

• ListObjectsV2 only reviews contents of the latest version of the ZIP in versioned buckets.
• AIStor does not support Range requests for GetObject and HeadObject for individual files.
• The ZIP file directory must be located within the last 100 MB.
• A single ZIP file may contain up to 100 million files. However, MinIO recommends a limit of 100,000 files per ZIP file for optimal performance and memory usage.

AIStor reads custom headers for files inside ZIP archives from each file entry’s Comment field.

To set custom headers, use the following format in the Comment field when creating the ZIP:

x-minio-meta:{"<key>":"<value>"}

Custom header keys are prefixed with X-Amz-Meta- when returned in responses, with the following exceptions:

• content-type - Returns as the Content-Type response header.
• content-encoding - Returns as the Content-Encoding response header.
• x-amz-tagging - Returns as the X-Amz-Tagging response header.

See the custom header example for how to create custom headers in several different languages and then verify the headers with curl.

The following examples demonstrate accessing files inside a ZIP archive using various SDKs.

package main

import (
    "context"
    "io"
    "log"
    "os"

    "github.com/minio/minio-go/v7"
    "github.com/minio/minio-go/v7/pkg/credentials"
)

func main() {
    client, err := minio.New("localhost:9000", &minio.Options{
        Creds:  credentials.NewStaticV4("minioadmin", "minioadmin", ""),
        Secure: false,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Set the extract header
    opts := minio.GetObjectOptions{}
    opts.Set("x-minio-extract", "true")

    // Get a file inside a ZIP archive
    obj, err := client.GetObject(
        context.Background(),
        "my-bucket",
        "archive.zip/path/to/file.txt",
        opts,
    )
    if err != nil {
        log.Fatal(err)
    }
    defer obj.Close()

    io.Copy(os.Stdout, obj)
}

import boto3
from botocore.config import Config

s3 = boto3.client(
    's3',
    endpoint_url='http://localhost:9000',
    aws_access_key_id='minioadmin',
    aws_secret_access_key='minioadmin',
    config=Config(signature_version='s3v4')
)

# Get a file inside a ZIP archive
response = s3.get_object(
    Bucket='my-bucket',
    Key='archive.zip/path/to/file.txt',
    ExtraArgs={'x-minio-extract': 'true'}
)

print(response['Body'].read().decode('utf-8'))

const AWS = require('aws-sdk');

const s3 = new AWS.S3({
    endpoint: 'http://localhost:9000',
    accessKeyId: 'minioadmin',
    secretAccessKey: 'minioadmin',
    s3ForcePathStyle: true,
    signatureVersion: 'v4'
});

// Get a file inside a ZIP archive
const params = {
    Bucket: 'my-bucket',
    Key: 'archive.zip/path/to/file.txt'
};

const request = s3.getObject(params);
request.on('build', () => {
    request.httpRequest.headers['x-minio-extract'] = 'true';
});

request.send((err, data) => {
    if (err) {
        console.error(err);
        return;
    }
    console.log(data.Body.toString());
});

The following examples demonstrate creating a ZIP file with custom headers in different languages.

package main

import (
    "archive/zip"
    "os"
)

func main() {
    zipFile, _ := os.Create("data.zip")
    defer zipFile.Close()

    zipWriter := zip.NewWriter(zipFile)
    defer zipWriter.Close()

    // Add file with custom metadata in comment
    header := &zip.FileHeader{
        Name:    "report.csv",
        Method:  zip.Deflate,
        Comment: `x-minio-meta:{"department":"finance","content-type":"text/csv"}`,
    }

    writer, _ := zipWriter.CreateHeader(header)
    writer.Write([]byte("id,name,value\n1,test,100\n2,example,200\n"))
}

import zipfile

with zipfile.ZipFile('data.zip', 'w') as zf:
    # Add a file with custom metadata headers
    info = zipfile.ZipInfo('report.csv')
    info.comment = b'x-minio-meta:{"department":"finance","content-type":"text/csv"}'
    zf.writestr(info, 'id,name,value\n1,test,100\n2,example,200\n')

const JSZip = require('jszip');
const fs = require('fs');

const zip = new JSZip();

// Add file with custom metadata in comment
zip.file('report.csv', 'id,name,value\n1,test,100\n2,example,200\n', {
    comment: 'x-minio-meta:{"department":"finance","content-type":"text/csv"}'
});

zip.generateAsync({ type: 'nodebuffer' })
    .then(content => {
        fs.writeFileSync('data.zip', content);
    });

Upload the ZIP file to your bucket using the MinIO Client:

mc cp data.zip myminio/my-bucket/

Then retrieve a file from the ZIP with custom headers using curl:

# Retrieve the file from inside the ZIP archive
curl -X GET \
  -H "x-minio-extract: true" \
  --user ACCESS_KEY:SECRET_KEY \
  -i \
  http://localhost:9000/my-bucket/data.zip/report.csv

# Response includes custom headers:
# HTTP/1.1 200 OK
# Content-Type: text/csv
# X-Amz-Meta-Department: finance
# ...

Custom headers for individual files with the ZIP archive require AIStor Server RELEASE.2026-02-02T23-40-11Z or later.