yauzl - Node.js Zip File Reader

Common errors

• JavaScript heap out of memory

  cause `lazyEntries` option was `false`, leading to all entries being buffered or processed too quickly for large zip files or those with many small entries.
  fix Set `lazyEntries: true` when opening the zip file and manually call `zipfile.readEntry()` after each entry's data stream has finished processing.

• Error: Invalid or unsupported zip file. (End of Central Directory Record not found)

  cause The input file is not a valid ZIP archive, or it's severely corrupted, preventing `yauzl` from locating the central directory.
  fix Verify that the input file is indeed a valid and uncorrupted `.zip` archive. Check file integrity or source.

• Error: Entry filename contains unsafe characters

  cause `yauzl`'s `validateFileName()` detected characters or patterns (like absolute paths, `..` segments, or backslashes with `strictFileNames: true`) that are considered unsafe for extraction.
  fix Inspect `entry.fileName`. If the name is genuinely unsafe, reject the entry. If backslashes are the issue and expected from non-conformant zips, ensure `strictFileNames: false` (the default) and `decodeStrings: true`.

• Error: Z_DATA_ERROR: incorrect header check

  cause The zlib decompression stream encountered corrupted or invalid compressed data for a file entry.
  fix This indicates a corruption within the zip file's contents for a specific entry. The zip file itself might be damaged. There is no code fix for a corrupted source file; you may need to acquire an uncorrupted archive.

• RangeError: Zip entry size mismatch

  cause `validateEntrySizes` was `true` (default) and the actual uncompressed size of an entry did not match the size reported in the zip file's metadata, potentially indicating a zip bomb or corrupted data.
  fix Handle the error gracefully. This is a security feature. The zip file might be intentionally malicious or simply corrupted. Ensure `yauzl` is updated to the latest stable version to benefit from all fixes and validations.

Warnings

• breaking Version 3.0.0 introduced breaking changes, including dropping support for Node.js versions older than 12. Additionally, implementations of `RandomAccessReader` (for custom back-ends) must now implement a `_destroy` method instead of `destroy` to align with Node.js stream standards.
  Fix: Ensure your Node.js environment is version 12 or newer. If implementing a custom `RandomAccessReader`, rename the `destroy` method to `_destroy` and update its signature to `_destroy(err, callback)`.
• breaking CVE-2026-31988: A denial of service vulnerability exists in `yauzl` version 3.2.0 due to an off-by-one error in a timestamp parser. Processing a specially crafted zip file could crash the Node.js process.
  Fix: Upgrade `yauzl` to version 3.3.0 or higher immediately. This fix addresses the vulnerability and prevents application crashes from malformed zip files.
• gotcha The `lazyEntries` option defaults to `false`. While this allows piping file data from all entries in parallel, it can lead to excessive memory consumption for zip files containing many entries. For better memory control, especially with large archives, `lazyEntries: true` is highly recommended.
  Fix: Always set `lazyEntries: true` in the `options` object when calling `yauzl.open()`, and manually call `zipfile.readEntry()` after processing each entry to control memory usage.
• gotcha The `validateEntrySizes` option defaults to `true` and ensures an entry's reported uncompressed size matches its actual size, which helps defend against zip bomb attacks. Disabling this option (setting it to `false`) removes this crucial validation, potentially exposing the application to exploits or unexpected behavior from malformed archives.
  Fix: Keep `validateEntrySizes` set to `true` (the default). If you must disable it, implement custom heuristics for size validation and error handling to mitigate risks from malicious or malformed zip files.
• gotcha The `strictFileNames` option defaults to `false`. This default behavior replaces backslashes (`\`) in `entry.fileName` with forward slashes (`/`), allowing `yauzl` to read non-conformant zip files created by some Microsoft tools. If `strictFileNames` is set to `true`, entries with backslashes will result in an error when `decodeStrings` is also `true`.
  Fix: Consider the origin of your zip files. If interoperability with Microsoft-created zip files is necessary, leave `strictFileNames: false`. If strict adherence to the ZIP spec regarding filenames is critical, set `strictFileNames: true` and handle potential errors for invalid filenames.
• gotcha The `decodeStrings` option defaults to `true`, causing `yauzl` to decode filenames and comments using CP437 or UTF-8. If set to `false`, `entry.fileName`, `entry.fileComment`, and `zipfile.comment` will be `Buffer` objects instead of strings, and automatic filename validation (via `validateFileName()`) will be bypassed.
  Fix: Unless you have a specific need to handle raw filename buffers (e.g., custom encoding), keep `decodeStrings: true` for proper string decoding and automatic filename validation.

Install

• npm install yauzl npm
• yarn add yauzl yarn
• pnpm add yauzl pnpm

Imports

• yauzl
  wrong:

  const yauzl = require('yauzl'); // CommonJS in ESM context without adapter

  correct:

  import yauzl from 'yauzl';

  While primarily a CommonJS module, Node.js allows importing it as a default export in ESM environments. For older Node.js versions or strict CJS, use require().
• open
  wrong:

  import { open } from 'yauzl'; // Not a named export for the main function.

  correct:

  import yauzl from 'yauzl'; yauzl.open(...);

  The primary `open` function is a method on the `yauzl` default export.
• ZipFile
  wrong:

  import { ZipFile } from 'yauzl'; // Not a named export

  correct:

  import yauzl from 'yauzl'; // Access ZipFile class via yauzl.ZipFile

  The `ZipFile` class, if needed directly for advanced usage, is available as a property of the main `yauzl` module object. It's usually instantiated internally by `yauzl.open`.

Quickstart

Demonstrates how to open a zip file, process entries one by one using `lazyEntries`, handle both files and directories, and stream content to disk.

import * as fs from 'fs';
import * as path from 'path';
import yauzl from 'yauzl';

const zipFilePath = 'path/to/your/archive.zip';
const extractDir = 'path/to/extract/to';

fs.mkdirSync(extractDir, { recursive: true });

yauzl.open(zipFilePath, { lazyEntries: true, autoClose: true }, (err, zipfile) => {
  if (err) throw err;

  zipfile.on('entry', (entry) => {
    const entryPath = path.join(extractDir, entry.fileName);
    if (//$/.test(entry.fileName)) {
      // Directory file names end with '/'
      fs.mkdirSync(entryPath, { recursive: true });
      zipfile.readEntry();
    } else {
      // File entry
      zipfile.openReadStream(entry, (err, readStream) => {
        if (err) throw err;
        readStream.on('end', () => {
          zipfile.readEntry();
        });
        // Ensure parent directory exists for the file
        fs.mkdirSync(path.dirname(entryPath), { recursive: true });
        readStream.pipe(fs.createWriteStream(entryPath));
      });
    }
  });

  zipfile.on('end', () => {
    console.log('Zip extraction complete.');
  });

  // Start reading entries
  zipfile.readEntry();
});