Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
unzipper
✓ import * as unzipper from 'unzipper';
✗ import unzipper from 'unzipper';
const unzipper = require('unzipper');
The library exports a default object containing the Open namespace and other utilities. For ESM, prefer `import * as unzipper` to get all exports. CommonJS `require('unzipper')` works similarly. Direct default import `import unzipper` may lead to issues.
Open.file
✓ import * as unzipper from 'unzipper';
const directory = await unzipper.Open.file('path/to/archive.zip');
✗ import { Open } from 'unzipper';
const directory = await Open.file('path/to/archive.zip');
Open is a static property of the main unzipper export, not a named export itself. Access it via `unzipper.Open`.
directory.files[0].stream
✓ import * as unzipper from 'unzipper';
const directory = await unzipper.Open.file('archive.zip');
directory.files[0].stream();
✗ directory.files[0].pipe(...);
The `stream()` method returns a readable stream; you must call it to get the stream object before piping. Similarly, `buffer()` must be called to return a Promise.
This quickstart demonstrates how to open a local ZIP file, list its contents, extract all files to a specified destination, and then read the content of a specific file into a buffer using unzipper's asynchronous API.
import * as unzipper from 'unzipper';
import fs from 'fs';
import path from 'path';
async function extractZipFile(zipFilePath, destinationPath) {
try {
console.log(`Opening zip file: ${zipFilePath}`);
const directory = await unzipper.Open.file(zipFilePath);
console.log(`Found ${directory.files.length} files in the archive.`);
// Ensure destination directory exists
await fs.promises.mkdir(destinationPath, { recursive: true });
console.log(`Extracting to: ${destinationPath}`);
// Extract all files to the destination path
await directory.extract({ path: destinationPath });
console.log('All files extracted successfully!');
// Example: Read the content of a specific file as a buffer
const firstFile = directory.files.find(f => !f.dir);
if (firstFile) {
console.log(`Reading content of first file: ${firstFile.path}`);
const contentBuffer = await firstFile.buffer();
console.log(`Content of ${firstFile.path} (first 50 bytes):\n${contentBuffer.toString('utf8', 0, Math.min(contentBuffer.length, 50))}...`);
}
} catch (error) {
console.error('Error during zip extraction:', error);
process.exit(1);
}
}
// To make this runnable, create a dummy zip file or provide a real path.
// For example, using a temporary file created by another process or a known zip.
// const dummyZipPath = '/tmp/test.zip';
// const dummyDestPath = '/tmp/extracted';
// extractZipFile(dummyZipPath, dummyDestPath);
// Placeholder for a real zip file if running directly.
// In a real application, these paths would come from user input or configuration.
const exampleZipPath = process.env.ZIP_FILE_PATH || path.join(process.cwd(), 'example.zip');
const exampleDestPath = process.env.EXTRACT_TO_PATH || path.join(process.cwd(), 'extracted_files');
if (!fs.existsSync(exampleZipPath)) {
console.warn(`Warning: Example zip file not found at ${exampleZipPath}. Please create one or set ZIP_FILE_PATH.`);
console.warn('To test, you can create a simple zip like: `echo "hello" > file1.txt && zip example.zip file1.txt`');
} else {
extractZipFile(exampleZipPath, exampleDestPath);
}
Errors
Common errors & fixes
TypeError: unzipper.Open.file is not a function
Incorrect import statement or accessing `Open` directly without the `unzipper` namespace.
fixUse `import * as unzipper from 'unzipper';` for ESM or `const unzipper = require('unzipper');` for CommonJS, then access via `unzipper.Open.file`. Error: Corrupted zip: CRC mismatch
The ZIP file is genuinely corrupted, incomplete, or the wrong password was provided for an encrypted entry.
fixVerify the integrity of the ZIP file, ensure it downloaded completely, and double-check the password for any encrypted files.
Error: 'Range not satisfiable' or similar HTTP 4xx error when using Open.url
The remote server hosting the ZIP file does not support HTTP Range requests, which unzipper relies on to read specific parts of the archive efficiently.
fixEnsure the server supports Range headers. If not, you might need to download the entire ZIP file first and process it locally using `Open.file`.
Error: Missing password for encrypted file
Attempting to `stream()` or `buffer()` an encrypted file without providing the correct password.
fixProvide the correct password as an argument to the `stream()` or `buffer()` method for encrypted file entries (e.g., `file.stream('yourPassword')`). Audit
Dependencies
requestoptionalRequired for the Open.url method to fetch remote zip files, as unzipper does not bundle a request library.