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.
gunzip
✓ const gunzip = require('gulp-gunzip')
✗ import gunzip from 'gulp-gunzip'
This package is CommonJS-only. Direct ESM `import` is not supported without a transpiler or a Gulpfile configured for ESM (e.g., `gulpfile.mjs`) and potentially dynamic imports for legacy CJS modules.
gulp
✓ const gulp = require('gulp')
✗ import gulp from 'gulp'
Gulp itself can support ESM in `gulpfile.mjs` or with `type: module` in `package.json`, but many older Gulpfiles and plugins still predominantly use CommonJS `require`.
This quickstart demonstrates how to uncompress local `.gz` files using `gulp-gunzip` and how to integrate it into a pipeline for processing remote (or simulated remote) archives, showcasing its streaming capabilities within Gulp. It also includes necessary setup for dummy files and directories.
const gulp = require('gulp');
const gunzip = require('gulp-gunzip');
const untar = require('gulp-untar'); // Example for chained usage
const source = require('vinyl-source-stream'); // Example for fetching remote files
const request = require('request'); // Example for fetching remote files
const path = require('path');
const fs = require('fs');
// Ensure output directories exist
const compressedDir = path.join(__dirname, 'compressed');
const uncompressedDir = path.join(__dirname, 'uncompressed');
const outputDir = path.join(__dirname, 'output');
if (!fs.existsSync(compressedDir)) fs.mkdirSync(compressedDir);
if (!fs.existsSync(uncompressedDir)) fs.mkdirSync(uncompressedDir);
if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir);
// Create a dummy gzipped file for the first task
const zlib = require('zlib');
const dummyContent = 'This is a test content for the gzipped file.';
zlib.gzip(dummyContent, (err, buffer) => {
if (!err) {
fs.writeFileSync(path.join(compressedDir, 'testfile.txt.gz'), buffer);
console.log('Dummy gzipped file created: compressed/testfile.txt.gz');
}
});
gulp.task('uncompress-local', function () {
console.log('Starting local uncompression...');
return gulp.src(path.join(compressedDir, '*.gz'))
.pipe(gunzip())
.pipe(gulp.dest(uncompressedDir))
.on('end', () => console.log('Local files uncompressed to: ' + uncompressedDir));
});
// Example of uncompressing a remote .tar.gz file (requires 'request' and 'vinyl-source-stream')
// NOTE: 'http://example.org/some-file.tar.gz' will likely result in a 404/dummy content
// For a real example, replace with a valid .tar.gz URL.
gulp.task('uncompress-remote', function (done) {
console.log('Attempting remote uncompression...');
// This URL is illustrative. A real URL to a .tar.gz would be needed.
const remoteFileUrl = 'https://www.google.com/robots.txt'; // Using a simple file for demonstration
const filename = 'remote-file.gz'; // Pretend it's gzipped for this demo
// Using a simplified request for a non-gzipped file for demonstration purposes if remoteFileUrl is not a .gz
// For actual .tar.gz, ensure the URL points to one and pipe through gunzip/untar
request(remoteFileUrl)
.pipe(source(filename))
.pipe(gunzip().on('error', (err) => {
console.error('Gunzip error on remote stream:', err.message);
// Handle cases where the remote file is not actually gzipped
done(); // Call done to complete the task even on error
}))
.pipe(gulp.dest(outputDir))
.on('end', () => {
console.log('Remote (simulated) file processed to: ' + outputDir);
done();
})
.on('error', (err) => {
console.error('Request stream error:', err.message);
done(err);
});
});
gulp.task('default', gulp.series('uncompress-local', 'uncompress-remote'));
Errors
Common errors & fixes
Error: Cannot read property 'pipe' of undefined
This typically occurs when `gulp.src` does not find any files matching the glob pattern, or a preceding stream in the pipeline errors out silently, resulting in an undefined stream being passed to `.pipe(gunzip())`.
fixVerify that `gulp.src('./compressed/*.gz')` is correctly pointing to existing gzipped files. Add error handling to upstream pipes to diagnose silent failures (e.g., `.on('error', console.error)`). Error: incorrect header check
This error usually indicates that the input file is not a valid gzip file or is corrupted. `gulp-gunzip` uses Node.js's `zlib` internally, which throws this error for malformed gzip data.
fixEnsure that the files being processed by `gulp-gunzip` are legitimate and uncorrupted gzip archives. You can pre-validate files using `zlib.gunzip` directly or other file integrity checks.
Error: unexpected EOF
This error suggests that the input gzip file ended prematurely or was truncated, leading to an incomplete data stream for decompression.
fixCheck the source of your `.gz` files for completeness. This can happen with incomplete downloads or corrupted storage. Ensure that the entire gzipped file has been received before piping it to `gulp-gunzip`.
Audit
Dependencies
gulprequiredRequired as the core build system to run this plugin. gulp-gunzip operates as a plugin within a Gulp task.