How do I update to Gulp 4?

Written by Mike Street on 22nd March 2016

(Last updated 6th March 2020)


Gulp is a fantastic build tool for compiling your SCSS, Less and SVG sprites that we use at Liquid Light.

For a while now, the gulpJS team have been working on Version 4. This version features some nice additions to the build tool but does also feature some substantial breaking changes. Upgrading is simple, but does require a few tweaks.

Upgrading gulp to v4

Note: The $ shows the command is to be run on the command line and shouldn’t be typed

$ npm install -g gulp
$ gulp -v
CLI version 2.0.1

If you are in a gulp project, a local version will be listed below the CLI version

Install gulp 4 locally

Once globally installed, gulp v4 will then need to be installed on a per-project basis.

$ npm install gulp --save-dev

If in your package.json file gulp is listed under dependencies, then replace the --save-dev with just --save.

You should now have gulp v4 installed and ready to go. This can be verified by running the version command above

Running gulp -v once again should now give you

$ gulp -v
CLI version 2.0.1
Local version 4.0.0

Updating your gulpfile

Now you have v4 successfully installed, you’ll need to do a few updates to your gulpfile.js. The best thing to do is run gulp and follow the errors that you get.

When you get an error, you will be faced with several lines of what appears to be jargon.

The first thing you need to look for is the error message. This will be something like

Error: Error message here

Make a note of that. The second line to look for is the one that includes the path to your gulpfile with some numbers afterwards. This is what mine looks like:

at Object.<anonymous> /Sites/gulp-v4/gulpfile.js:418:6

This tells you the error was generated in your gulpfile at line 418, character 6.

I’ve tested below some errors I came across during the update and how to fix them.

AssertionError: Task function must be specified

This error for me was thrown because of:

gulp.task('default', ['del'], function() {
    // default task code here

Where the del task is being run before the default task.

To resolve this, you need to specify that the del and following function are to be run in a series.

To resolve this, change the code to:

gulp.task('default', gulp.series('del', function() { 
    // default task code here

Note: because you are opening a parenthesis for gulp.series, don’t forget to add an extra closing one after the function.

Make sure you update the rest of your gulpfile to follow suit.

The gulp has updated this syntax for running tasks in series to add the functionality of running tasks in parallel with gulp.parallel. More can be read about it in the gulp docs.

Did you forget to signal async completion?

The following tasks did not complete: default, del
Did you forget to signal async completion?

This error occurred on an anonymous function (the one occurring after del in the example above).

Gulp v4 requires a stream, promise, event emitter, child process or observable to be returned from a function or task. This was resolved in the simplest case of passing a parameter into the function and firing it after the task is completed.


gulp.task('default', gulp.series(function(done) {    
    // task code here

(Note the done in-between the parenthesis when the function opens and then it firing at the end).

I specifically got this error when trying to run the del npm package.

My del package was set to call del.sync which returns an array, Gulp requires one of the stream, promise, event emitter, child process or observable to be returned, which del does by default.

return del(dirs);

Gulp watcher with change event and paths

With gulp v3, the watcher would return the path of the modified file within the function it called.

For example, the output for the below would be an object with the location of the file modified and event (e.g. changed).

gulp.task('watch', function(){'path/to/css/*.css').on('change', function(event) {
        // code to execute

With gulp 4, this doesn't seem to be the case. Instead, the watcher can fire some standard functions, but if you need filename based operations, these need to be moved to the changed function.

gulp.task('watch', function(){'path/to/css/*.css')
    .on('change', function(path, stats) {
        // code to execute on change
    .on('unlink', , function(path, stats) {
        // code to execute on delete

If you did need to fire a generic function when a file is changed while being watched, the gulp tutorials have an example of this.

Just a small reminder, if you are upgrading to Gulp 4 and have a shared project, the other developers will need to upgrade also.

If you have encountered any other errors, then feel free to drop a comment below or tweet us - we'd be more than happy to help and include the solution above for others!

Update 13/08/2018: Two years later and Gulp 4 still hasn't been released!

This article was posted in Development, Tools by Mike Street

  • Mike Street

    Mike Street

    Mike is our front-end developer who spends his days buried in CSS and Gulp. His evenings and weekends are spent tinkering with electronics and riding bikes.


There is this videos with Addy Osmani explaining more things about to gulp 4 - -

Tiago Celestino15/04/2016 15:17

Thanks a lot for this article! I'm looking forward to dive in to gulp 4 now.
I must say I'm pretty curious what your full gulpfile looks like ;-)

Gristel12/05/2016 22:30

It looks like it will take a years for final release :|

Yehor13/05/2016 15:40

Okay this worked very well, you covered all the problems I had when migrating from 3 to 4. Thank you
I had the most trouble understading the watcher function; I ended up doing this, which worked well:

gulp.task('watch', function() {
livereload.listen(); + config.styles.src_dir + '**/*' + config.styles.extension, gulp.parallel('styles')); + config.pug.src_dir + '**/*.pug', gulp.parallel('templates')); + config.scripts.src_dir + '**/*.coffee', gulp.parallel('scripts')); + config.fonts.src_dir + '**/*', gulp.parallel('fonts'));

Sebastian18/06/2016 11:58

Hi Sebastian,

That watch task looks about right - you have to specify a watch for each file-type/task you want to trigger. It's verbose but means you get lots of control over what triggers what

Mike Street21/06/2016 08:53

One thing that I had to do as well is listen to 'end' event to call done(). Example:
gulp.task('do-stuff', gulp.series('other-dep', function (done) {
return gulp.src(someFiles)
.on('end', function () { done(); });

Alaeddin13/07/2016 04:49

Thanks Alaeddin!

Mike Street20/07/2016 09:53

This article is really helpful! gulp.series and gulp.parallel are definitely my favorite features in gulp 4.

Shunfan Du26/07/2016 21:14

Thanks Shunfan - great to hear it helped.

Rick, it sounds like you don't have correct SSH access set up for Github? Try installing Gulp 4 over HTTPS instead:

npm install '' --save-dev

Mike Street31/08/2016 09:53

My present gulp version is

CLI version 3.9.1
Local version 4.0.0-alpha.2

But when i run gulp commad i'm getting this ERROR,

TypeError: Cannot read property 'apply' of undefined
at /usr/local/lib/node_modules/gulp/bin/gulp.js:129:19
at nextTickCallbackWith0Args (node.js:420:9)
at process._tickCallback (node.js:349:13)
at Function.Module.runMain (module.js:443:11)
at startup (node.js:139:18)
at node.js:968:3

Poornesh13/10/2016 07:10

I want to update gulp-cli to version 4.0

I tried this command $ npm install -g "gulpjs/gulp-cli#4.0"

But I'm getting path error.

Poornesh13/10/2016 07:20

Thank you for your simple but well-explained guide. I've just updated a project to gulp4 and am reasonably happy!

Ian P17/10/2016 12:44

Hi Poornesh,

What do you get when you run the "gulp -v" command?

Mike Street20/10/2016 11:32

Hi Poornesh,

Even I came across the same issue .
Make your gulp-cli version to 1.2.2 ,it will solve your problem.

Rajath22/10/2016 20:43

Not worth "upgrading".

Without `requireDir` functioning (tasks needing to be defined before depends) and with all dependencies needing to be in the same file, most of the organisational benefits of Gulp vanish and it becomes an unmaintainable monolith.

Yellow08/01/2017 23:58

With the watch function, you can use .on('all', function(){}) to fire tasks regardless of whether files are added, changed or removed. So .on('all') is much closer to Gulp 3's watch functionality.

Dan05/02/2017 10:46

Thanks for article! Please, answer, what syntax highlighter you use on this site?

Alex05/10/2017 09:23

Hi @Alex we use Prism.js

Oliver Rowlands05/10/2017 09:25

Hi @mikestreety,

Like @Poornesh I am having a similar problem:

gulpInst.start.apply(gulpInst, toRun);

TypeError: Cannot read property 'apply' of undefined
at /usr/local/lib/node_modules/gulp/bin/gulp.js:129:20
at _combinedTickCallback (internal/process/next_tick.js:131:7)
at process._tickCallback (internal/process/next_tick.js:180:9)
at Function.Module.runMain (module.js:678:11)
at startup (bootstrap_node.js:187:16)
at bootstrap_node.js:608:3

"gulp -v" yields
CLI version 3.9.1
Local version 4.0.0-alpha.2

The main reason I am interested in v4 is to run tasks in series, especially those related to clean and build.


noelspringer05/11/2017 12:44

Hi Noel,

Thanks for your comment. It seems you need to reinstall the Gulp CLI as it needs to be on 1.2.2 as detailed here:

Hope that helps!


Mike Street20/11/2017 09:00

node -v

npm -v

npm install 'gulpjs/gulp.git#4.0' --save-dev
When I'm trying to run this command on my local machine I'm getting this error.

npm ERR! Error while executing:
npm ERR! C:\Program Files\Git\cmd\git.EXE ls-remote -h -t ssh://'gulpjs/gulp.git
npm ERR!
npm ERR! Host key verification failed.
npm ERR! fatal: Could not read from remote repository.
npm ERR!
npm ERR! Please make sure you have the correct access rights
npm ERR! and the repository exists.
npm ERR!
npm ERR! exited with error code: 128

suresh15/06/2018 09:10

Having a whole section of this say "It's not that hard" is incredibly unnecessary and demeaning. It needlessly makes people feel like if they aren't able to fix their new gulp workflow, that they're an idiot. Please consider removing this portion of this article; otherwise, it is very helpful.

Julian13/08/2018 03:12

Hi Julian, many thanks for your feedback. I've updated the post - glad it helped!

Mike Street13/08/2018 09:49

Thanks for this awesome blog post. Helped me alot!

brewer11/11/2018 11:46

Thanks for this! I followed this article and got everything working!

FYI If you get an error like:
"TypeError: Cannot read property 'apply' of undefined"

Run 'npm install --global gulp-cli' and try again. That fixed it for me.

Javed21/11/2018 23:15

Thanks for sharing your knowledge. Longtime I didn't ran npm updates, and ran in issues today. You saved my night !

Simone11/12/2018 18:55

Time saver. Love your formatting, easy to read. Thank you.

Gonzalo16/04/2019 15:24

Thank you, Mike, this post is very helpful.

Thomas Factory23/09/2020 18:02

Post a comment

You are currently offline. Some pages or content may fail to load.