Registry / serialization / extract-zip

extract-zip

JSON →
library1.0.0jsnpmunverified

extract-zip is a pure JavaScript library for asynchronously extracting zip archives into a specified directory. It currently stands at version 2.0.1 and leverages the `yauzl` parser internally to handle zip file structures. Version 2.0.0 marked a significant update, introducing a modern Promise-based API that replaced the older callback-style approach, and adding official TypeScript definitions for enhanced developer experience. The library maintains an active release cadence, with recent updates (like v2.0.1) addressing critical maintenance issues such as the deprecated `process.umask` and clarifying Node.js minimum version requirements. It also offers a command-line interface for direct use. Its primary differentiators include its 100% JavaScript implementation, which avoids native binaries, and its adoption of the modern async/await pattern for all extraction operations, requiring Node.js 10.17.0 or newer.

npm install extract-zip
INSTALL
IMPORT
SIG · EXTRACT-ZIP
E
extract-zip
serializationjavascriptv1.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

extract (ESM)
✓ import extract from 'extract-zip'
✗ import { extract } from 'extract-zip'
The primary `extract` function is the default export for ES Modules. Use `await` as the API is Promise-based.
extract (CommonJS)
✓ const extract = require('extract-zip')
✗ const { extract } = require('extract-zip')
For CommonJS environments, `extract` is the module's default export. Avoid destructuring as it's not a named export.
ExtractOptions (TypeScript type)
✓ import type { ExtractOptions } from 'extract-zip'
✗ import { ExtractOptions } from 'extract-zip'
Use `import type` for importing only the type definition, which is recommended for clarity and bundler optimization in TypeScript.

This quickstart demonstrates how to use `extract-zip` with its Promise-based API to extract a zip file. It sets up a temporary directory for extraction and includes basic error handling, noting that a real zip file must exist at the specified source path for actual operation.

import extract from 'extract-zip'; import { mkdir, mkdtemp } from 'node:fs/promises'; import { join } from 'node:path'; import { tmpdir } from 'node:os'; async function runExtractionDemo() { // 1. Define source and target paths. // For a real scenario, 'path/to/your/archive.zip' should be an actual zip file. // For this demo, we'll create a temporary directory for extraction. const tempExtractionDir = await mkdtemp(join(tmpdir(), 'extract-zip-demo-')); const sourceZipPath = join(__dirname, 'test.zip'); // Assume a 'test.zip' exists alongside this script // For a real run, ensure this file exists. const targetDirectoryPath = join(tempExtractionDir, 'extracted-content'); console.log(`Attempting to extract from: ${sourceZipPath}`); console.log(`To target directory: ${targetDirectoryPath}`); try { // Ensure the target directory exists before extraction (optional, extract-zip usually creates it) await mkdir(targetDirectoryPath, { recursive: true }); // 2. Call the extract function. await extract(sourceZipPath, { dir: targetDirectoryPath }); console.log('✅ Extraction complete!'); console.log(`Content should be in: ${targetDirectoryPath}`); // Example: To list extracted files: // import { readdir } from 'node:fs/promises'; // const files = await readdir(targetDirectoryPath); // console.log('Extracted files:', files); } catch (err: any) { console.error('❌ Extraction failed:', err.message); if (err.code === 'ENOENT') { console.error(`Hint: Make sure '${sourceZipPath}' exists and is a valid zip file.`); } else if (err.message.includes('End of Central Directory Record not found')) { console.error('Hint: The file might be corrupted or not a valid zip archive.'); } } finally { // 3. Clean up the temporary directory. Uncomment for automatic cleanup. // console.log(`Cleaning up temporary directory: ${tempExtractionDir}`); // await rm(tempExtractionDir, { recursive: true, force: true }); console.log(`Temporary directory created at: ${tempExtractionDir}. Please inspect and remove manually if needed.`); } } runExtractionDemo().catch(console.error);
extract-zip --version
Debug
Known issues
breakingThe callback-style API was entirely removed in version 2.0.0. All operations now return Promises and should be handled with `await` or `.then/.catch`.
fix
Rewrite extraction logic to use `async/await`: `await extract(source, { dir: target })` instead of `extract(source, { dir: target }, callback)`.
affects: >=2.0.0
breakingSupport for Node.js versions older than 10.12 was dropped in version 2.0.0. The library leverages `fs.promises`, which stabilized in newer Node versions.
fix
Upgrade your Node.js environment to version 10.12.0 or newer. For best compatibility with current versions, upgrade to >=10.17.0.
affects: >=2.0.0
breakingThe minimum required Node.js version was corrected to 10.17.0 in version 2.0.1, due to dependencies on `fs.promises` stability. This means installations on Node.js versions between 10.12.0 and 10.16.x that worked with v2.0.0 will now fail with v2.0.1.
fix
Ensure your Node.js environment is at version 10.17.0 or higher. It's recommended to use an actively maintained Node.js LTS version.
affects: >=2.0.1
gotchaThe `onEntry` option function expects two arguments: `(entry, zipfile)`. The `entry` object is forwarded directly from the `yauzl` library, and `zipfile` is the `yauzl` instance itself. Always ensure `zipfile` is closed when you are done.
fix
Ensure your `onEntry` callback correctly handles `(entry, zipfile)` arguments if you need access to the `yauzl` instance or raw entry data, and explicitly close the `zipfile` if you open it manually within the handler.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: extract is not a function
Attempting to use `extract` in a CommonJS module with incorrect destructuring or trying to use the old callback API after upgrading to v2.0.0+.
fix
For CommonJS, use `const extract = require('extract-zip')`. For all versions >= 2.0.0, ensure you're using the Promise-based API with `await extract(source, options)`.
Error: Your Node.js version is too old. This module requires Node.js >= 10.17.0.
Running `extract-zip` v2.0.1 or later on an unsupported Node.js version.
fix
Upgrade your Node.js environment to version 10.17.0 or newer. Check the official Node.js website for LTS releases.
Error: End of Central Directory Record not found
The provided source file is either not a valid zip archive or is corrupted, preventing the `yauzl` parser from identifying the central directory.
fix
Verify that the `source` path points to a legitimate and uncorrupted `.zip` file. Try opening the zip file manually to confirm its integrity.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies
yauzlrequiredCore library for parsing ZIP files. `extract-zip` uses it internally for handling the ZIP file format.
Agent activity
8 hits · last 30 days
node
6
Bingbot
1
OpenAI (training)
1
Resources