Handling ZIP Archives in Node.js Applications
These libraries enable Node.js applications to create, read, and extract ZIP files. adm-zip offers a synchronous API for simple tasks, while extract-zip provides a promise-based interface for extraction. unzip is a legacy package that is no longer maintained. unzipper serves as its active fork with streaming support. yauzl is a low-level, read-only stream library focused on robustness and compliance.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Handling ZIP Archives in Node.js Applications
Working with ZIP files in Node.js requires choosing the right tool for your specific needs — whether that is speed, memory efficiency, or ease of use. The five packages adm-zip, extract-zip, unzip, unzipper, and yauzl each take a different approach to handling archives. Let's break down how they differ in real-world scenarios.
📦 Extraction Styles: Sync vs Stream vs Promise
How a library handles file operations affects your application's performance. Blocking the main thread can freeze your server, while streaming keeps things smooth.
adm-zip works synchronously. It reads the whole file into memory and blocks execution until done.
const AdmZip = require('adm-zip');
const zip = new AdmZip('archive.zip');
zip.extractAllTo('./destination', true);
// Execution pauses here until extraction finishes
extract-zip uses Promises and handles streams internally. It is async but high-level.
const extract = require('extract-zip');
await extract('archive.zip', { dir: './destination' });
// Returns a promise, non-blocking
unzip uses streams but is deprecated. It was non-blocking but is unsafe to use now.
const unzip = require('unzip');
fs.createReadStream('archive.zip').pipe(unzip.Extract({ path: './destination' }));
// Deprecated: Do not use in production
unzipper also uses streams and is the maintained replacement for unzip.
const unzipper = require('unzipper');
fs.createReadStream('archive.zip').pipe(unzipper.Extract({ path: './destination' }));
// Non-blocking, safe for large files
yauzl provides a low-level stream interface for reading entries manually.
const yauzl = require('yauzl');
yauzl.open('archive.zip', { lazyEntries: true }, (err, zipfile) => {
zipfile.readEntry();
// You must handle each entry stream manually
});
🛠️ Reading and Writing Capabilities
Not all libraries can do everything. Some are read-only, while others let you create archives too.
adm-zip supports both reading and writing. You can create new ZIP files easily.
const zip = new AdmZip();
zip.addFile('text.txt', Buffer.from('hello'));
zip.writeZip('new-archive.zip');
extract-zip is extraction only. It cannot create ZIP files.
// No API for creating archives
await extract('source.zip', { dir: './out' });
unzip was extraction only. It could not create archives.
// No API for creating archives
// Deprecated functionality
unzipper focuses on extraction and reading. It does not support creating ZIPs.
// No API for creating archives
// Focuses on parsing and extracting streams
yauzl is strictly read-only. It is designed for parsing, not writing.
// No API for creating archives
yauzl.open('file.zip', {}, (err, zipfile) => { /* read only */ });
⚠️ Maintenance and Stability
Using unmaintained code puts your project at risk. Security patches and bug fixes depend on active maintainers.
adm-zip is actively maintained. It receives updates for security and compatibility.
// Safe to use for synchronous tasks
const AdmZip = require('adm-zip');
extract-zip is well-maintained. It is a popular choice for Electron apps and CLI tools.
// Safe for async extraction
const extract = require('extract-zip');
unzip is deprecated. The repository is archived and issues are closed.
// WARNING: Deprecated
// npm install unzip (Not recommended)
unzipper is the active fork. It fixes bugs from the original unzip package.
// Safe replacement for unzip
const unzipper = require('unzipper');
yauzl is stable and maintained. It is known for strict spec compliance.
// Safe for robust reading
const yauzl = require('yauzl');
📊 Summary Table
| Package | Sync/Async | Read/Write | Maintenance | Best For |
|---|---|---|---|---|
adm-zip | Sync | Both | Active | Simple scripts, creating ZIPs |
extract-zip | Async (Promise) | Read Only | Active | Easy extraction in apps |
unzip | Async (Stream) | Read Only | Deprecated | ❌ Do Not Use |
unzipper | Async (Stream) | Read Only | Active | Streaming large files |
yauzl | Async (Stream) | Read Only | Active | Custom parsing logic |
💡 Final Recommendation
Your choice depends on whether you need to create archives or just read them, and how much control you need over the process.
adm-zip is the go-to for creating ZIPs or when you want the simplest API for small files. Just remember it blocks the event loop.
extract-zip is best for standard extraction tasks where you want async behavior without managing streams yourself.
unzipper is the right choice for server-side processing of large files where streaming is required to save memory.
yauzl fits when you are building a tool that needs to inspect ZIP contents without necessarily extracting them to disk.
unzip should be avoided entirely. Switch to unzipper if you find legacy code using it.
Final Thought: For most modern Node.js applications, a combination of extract-zip for simplicity and unzipper for streaming offers the best balance of safety and performance.
How to Choose: adm-zip vs extract-zip vs unzip vs unzipper vs yauzl
- adm-zip:
Choose
adm-zipfor simple scripts where blocking the event loop is acceptable, such as CLI tools or build steps. It is one of the few options that supports creating ZIP files easily without complex stream piping. - extract-zip:
Choose
extract-zipwhen you need a straightforward, promise-based way to extract archives to a folder. It handles the stream piping internally, reducing boilerplate code for common extraction tasks. - unzip:
Do NOT choose
unzipfor new projects. It is deprecated and unmaintained, containing known bugs and security issues that will not be fixed. - unzipper:
Choose
unzipperif you need to stream extract files or read entries without writing to disk immediately. It is the maintained successor tounzipand works well for processing large files. - yauzl:
Choose
yauzlwhen you need a robust, low-level reader that strictly follows the ZIP specification. It is ideal for building custom tools where you need fine-grained control over reading entries without extraction features.
Popular Comparisons
README for adm-zip
ADM-ZIP for NodeJS
ADM-ZIP is a pure JavaScript implementation for zip data compression for NodeJS.
Installation
With npm do:
$ npm install adm-zip
Electron file system support described below.
What is it good for?
The library allows you to:
- decompress zip files directly to disk or in memory buffers
- compress files and store them to disk in .zip format or in compressed buffers
- update content of/add new/delete files from an existing .zip
Dependencies
There are no other nodeJS libraries that ADM-ZIP is dependent of
Examples
Basic usage
var AdmZip = require("adm-zip");
// reading archives
var zip = new AdmZip("./my_file.zip");
var password = "1234567890";
var zipEntries = zip.getEntries(); // an array of ZipEntry records - add password parameter if entries are password protected
zipEntries.forEach(function (zipEntry) {
console.log(zipEntry.toString()); // outputs zip entries information
if (zipEntry.entryName == "my_file.txt") {
console.log(zipEntry.getData().toString("utf8"));
}
});
// outputs the content of some_folder/my_file.txt
console.log(zip.readAsText("some_folder/my_file.txt"));
// extracts the specified file to the specified location
zip.extractEntryTo(/*entry name*/ "some_folder/my_file.txt", /*target path*/ "/home/me/tempfolder", /*maintainEntryPath*/ false, /*overwrite*/ true);
// extracts everything
zip.extractAllTo(/*target path*/ "/home/me/zipcontent/", /*overwrite*/ true);
// creating archives
var zip = new AdmZip();
// add file directly
var content = "inner content of the file";
zip.addFile("test.txt", Buffer.from(content, "utf8"), "entry comment goes here");
// add local file
zip.addLocalFile("/home/me/some_picture.png");
// get everything as a buffer
var willSendthis = zip.toBuffer();
// or write everything to disk
zip.writeZip(/*target file name*/ "/home/me/files.zip");
// ... more examples in the wiki
For more detailed information please check out the wiki.
Electron original-fs
ADM-ZIP has supported electron original-fs for years without any user interractions but it causes problem with bundlers like rollup etc. For continuing support original-fs or any other custom file system module. There is possible specify your module by fs option in ADM-ZIP constructor.
Example:
const AdmZip = require("adm-zip");
const OriginalFs = require("original-fs");
// reading archives
const zip = new AdmZip("./my_file.zip", { fs: OriginalFs });
.
.
.
Security
Please report security vulnerabilities privately. See SECURITY.md.