Gulp 5
last modified November 15, 2026
In this article we look at what changed in Gulp 5 compared to Gulp 4. The task API is almost identical, so most gulpfiles keep working. A few details changed under the hood, and one of them, the way files are read, can silently corrupt images. We test each change and finish with a migration checklist.
Gulp 5
Gulp is a streaming task runner for Node.js. Gulp 5 was released in
March 2024, more than five years after Gulp 4. The functions that gulpfiles
use every day, src, dest, series,
parallel, and watch, have the same names and the same
signatures. See the Gulp getting started
tutorial for an introduction.
The changes are in the dependencies. Gulp 5 reads and writes files with
vinyl-fs 4, which is built on streamx, a stream
library that replaces the Node.js streams used by vinyl-fs 3.
The command line tool is now gulp-cli 3.
Versions
We create a project and install Gulp. The --version option
prints the version of the command line interface and of the local Gulp package.
The npm ls command shows that vinyl-fs 4 and its
helpers, such as glob-stream, depend on streamx.
The package.json of Gulp 5.0.1 declares support for Node.js 10.13
and later, but plugins can require a newer version: the current
del package, for instance, is distributed as an ES module only.
$ mkdir gulp-five
$ cd gulp-five
$ npm init -y
$ npm i -D gulp
$ npx gulp --version
CLI version: 3.1.0
Local version: 5.0.1
$ npm ls streamx vinyl-fs glob-stream
gulp-five@1.0.0 ~/Documents/prog/js/gulp-five
└─┬ gulp@5.0.1
└─┬ vinyl-fs@4.0.2
├─┬ fs-mkdirp-stream@2.0.1
│ └── streamx@2.28.1 deduped
├─┬ glob-stream@8.0.4
│ └── streamx@2.28.1 deduped
├─┬ stream-composer@1.0.2
│ └── streamx@2.28.1 deduped
├── streamx@2.28.1
├─┬ to-through@3.0.0
│ └── streamx@2.28.1 deduped
├─┬ vinyl-sourcemap@2.0.0
│ └── streamx@2.28.1 deduped
└─┬ vinyl@3.0.1
└─┬ teex@1.0.1
└── streamx@2.28.1 deduped
Binary files and encoding
The most dangerous change concerns the encoding option of
src. Gulp 5 decodes the content of every file as UTF-8 text by
default, and encodes it again when the file is written. For text files in
UTF-8 this is invisible, but a binary file, such as an image, does not survive
the round trip: bytes that are not valid UTF-8 are replaced with the Unicode
replacement character.
The example copies a PNG image, a UTF-8 text file, and a text file in
Latin-1 encoding into two directories. The first task uses the defaults, the
second task sets encoding to false, which makes Gulp
read the raw bytes.
import { src, dest } from 'gulp';
export function copy() {
return src('src/*.{png,txt}')
.pipe(dest('dist'));
}
export function copyBinary() {
return src('src/*.{png,txt}', { encoding: false })
.pipe(dest('dist-ok'));
}
The two tasks are identical except for the options of src.
return src('src/*.{png,txt}', { encoding: false })
.pipe(dest('dist-ok'));
With encoding: false the file contents are passed through
untouched. Nothing is reported when the default is used: both tasks finish
successfully. Only the checksums tell the difference. The copy made with the
default encoding has a different checksum for the PNG image and for the
Latin-1 file, while the UTF-8 file is identical in both copies. The hex dump
shows that the byte e9 of the Latin-1 letter é was replaced
with the three bytes ef bf bd of the replacement character.
$ npx gulp copy
[12:44:58] Using gulpfile ~/Documents/prog/js/gulp-five/gulpfile.mjs
[12:44:58] Starting 'copy'...
[12:44:58] Finished 'copy' after 13 ms
$ npx gulp copyBinary
[12:44:58] Using gulpfile ~/Documents/prog/js/gulp-five/gulpfile.mjs
[12:44:58] Starting 'copyBinary'...
[12:44:58] Finished 'copyBinary' after 13 ms
$ md5sum src/*.{png,txt} dist/* dist-ok/*
fd4b795489b2ea455d481365c7f8d949 src/logo.png
70941b2a2a6a84556c97b2a3220ef4be src/latin1.txt
6e99834b7c3e3fd53529a5489725d7e8 src/utf8.txt
68d268dab6a93236da26ea6e5d6ca2ba dist/latin1.txt
576c8d01744c981218776334f452d0de dist/logo.png
6e99834b7c3e3fd53529a5489725d7e8 dist/utf8.txt
70941b2a2a6a84556c97b2a3220ef4be dist-ok/latin1.txt
fd4b795489b2ea455d481365c7f8d949 dist-ok/logo.png
6e99834b7c3e3fd53529a5489725d7e8 dist-ok/utf8.txt
$ xxd dist/latin1.txt
00000000: 6361 66ef bfbd 0a caf....
Streams and errors
Because the streams come from streamx, plugins behave a little
differently than under Gulp 4. The most visible difference concerns errors. The
pipe method does not forward an error from one stream to the next,
so when a plugin in the middle of a chain fails, Gulp may report success, or
report that the task never completed. The
Gulp error handling tutorial shows how to
make such failures visible with pipeline from the Node.js
stream/promises module. The
Gulp Terser tutorial shows a real case with
gulp-terser.
Plugins built on the Node.js Transform class still work,
because pipe accepts any stream. Plugins that are no longer maintained may depend on old libraries; run
npm audit after the upgrade and replace such plugins, as we did
with gulp-minify, which is superseded by
gulp-terser.
CommonJS gulpfiles still work
A gulpfile written for Gulp 4 does not have to be rewritten. This one uses
require, the string-based gulp.task function, and
gulp.series.
const gulp = require('gulp');
const terser = require('gulp-terser');
gulp.task('scripts', function () {
return gulp.src('src/*.js')
.pipe(terser())
.pipe(gulp.dest('dist'));
});
gulp.task('default', gulp.series('scripts'));
Gulp 5 runs the file unchanged. We point the command line to the file with
--gulpfile and keep the working directory with --cwd.
The task registry of Gulp 4, with gulp.task, is still available,
although the recommended way of defining tasks is to export functions.
$ npx gulp --gulpfile legacy/gulpfile.js --cwd .
[12:44:59] Using gulpfile ~/Documents/prog/js/gulp-five/legacy/gulpfile.js
[12:44:59] Starting 'default'...
[12:44:59] Starting 'scripts'...
[12:44:59] Finished 'scripts' after 28 ms
[12:44:59] Finished 'default' after 30 ms
$ cat dist/hello.js
const greet=e=>`Hello ${e}`;console.log(greet("Gulp"));
The same gulpfile as an ES module
The modern version of the same gulpfile is an ES module. The tasks are exported functions and the default export is the default task.
import { src, dest, series } from 'gulp';
import terser from 'gulp-terser';
export function scripts() {
return src('src/*.js')
.pipe(terser())
.pipe(dest('dist'));
}
export default series(scripts);
The .mjs extension tells Node.js to treat the file as an ES
module, so import and export work. The
ESM gulpfile tutorial covers this in detail.
The result is the same minified file as before.
$ npx gulp --gulpfile modern/gulpfile.mjs --cwd .
[12:44:59] Using gulpfile ~/Documents/prog/js/gulp-five/modern/gulpfile.mjs
[12:44:59] Starting 'default'...
[12:44:59] Starting 'scripts'...
[12:44:59] Finished 'scripts' after 31 ms
[12:44:59] Finished 'default' after 33 ms
$ cat dist/hello.js
const greet=e=>`Hello ${e}`;console.log(greet("Gulp"));
Migrating a gulpfile
Moving a project from Gulp 4 to Gulp 5 takes a few steps.
- Install the new version with
npm i -D gulp@5and check that every plugin inpackage.jsonstill works. - Add
encoding: falseto everysrccall that reads images, fonts, archives, or other binary files. - Replace unmaintained plugins;
npm auditpoints to the candidates. - Convert the gulpfile to an ES module (
gulpfile.mjs), which is necessary for ESM-only packages such asdelandgulp-imagemin. - Wrap fragile pipe chains in
pipelineso that errors fail the task. - Run every task once and compare the output directory with the old build.
Most gulpfiles need nothing more than the second step.
Source
Gulp 5.0.0 release notes, Gulp src API, vinyl-fs on GitHub, streamx on GitHub
In this article we have looked at the differences between Gulp 4 and Gulp 5:
the new stream library, UTF-8 decoding of file contents and the
encoding option, CommonJS and ES module gulpfiles, and the steps
of a migration. See also the ESM gulpfile and
Gulp src and dest tutorials.
Author
List all Gulp tutorials.