Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js zlib.createGunzip() method

Reference for zlib.createGunzip() in Node.js: decompress gzip data as a stream, handle truncated or corrupt input, multi-member files and safe output limits.

zlib.createGunzip() returns a Gunzip object, a Transform stream that reads gzip-compressed bytes and emits the original bytes. It decompresses as data arrives, so a multi-gigabyte .gz file can be processed in constant memory. Use it for reading .gz files, for HTTP responses sent with Content-Encoding: gzip and for any other gzip stream.

Related factories are createInflate(), createInflateRaw(), createUnzip() (detects gzip or zlib), createBrotliDecompress() and createZstdDecompress(). Errors in the input surface as an error event on the stream, which pipeline() turns into a rejected promise.

NODE
import { createGunzip } from 'node:zlib';
import { pipeline } from 'node:stream/promises';

await pipeline(compressedSource, createGunzip(), destination);

Try it

Node.js Reading a gzip stream line by line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Corrupt, truncated and multi-member input

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
zlib.createGunzip(options?: object): zlib.Gunzip   // a stream.Transform
zlib.createUnzip(options?: object): zlib.Unzip     // gzip or zlib, auto-detected
Name Description
options.chunkSize Size of output chunks. Default 16384.
options.windowBits Maximum history window (log2). Default 15, which handles every valid gzip stream.
options.finishFlush How to treat the end of input. Z_SYNC_FLUSH makes a truncated stream end without error, returning what was decoded.
options.maxOutputLength Applies to the buffer helpers, not to streams. Limit streams yourself by counting bytes.

Returns: a Gunzip stream that emits decompressed Buffers.

Errors: Z_DATA_ERROR with incorrect header check for data that is not gzip, Z_DATA_ERROR with incorrect data check for a checksum mismatch, and Z_BUF_ERROR with unexpected end of file for truncated input. They arrive as an error event and the stream is destroyed.

Usage notes

  • Always use pipeline() or listen for error. An unhandled error event on a stream crashes the process.
  • A truncated download is the most common production failure. The default behavior (error) is correct for most uses; pass finishFlush: constants.Z_SYNC_FLUSH only when partial data is acceptable, such as reading a log still being written.
  • Concatenated gzip members (as produced by appending .gz files with cat) decode as one stream.
  • Streams do not enforce an output size. To resist decompression bombs, count bytes passing through (for example in a small Transform) and destroy the stream with an error past your limit. See Decompression bombs.
  • Browsers decompress Content-Encoding: gzip on their own. A Node HTTP client does not, so pipe the response into createGunzip() when it carries that header (the global fetch() decodes it for you).
  • For web streams, DecompressionStream('gzip') provides the same capability with the standard API.