Written by Mike Street on 22nd March 2016

(Last updated 22nd April 2016)


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

The good news is you can upgrade and play with v4 for a particular project without having to change all of your gulp files. This is ideal if you want to see what gulp v4 means for your and your workflow before taking the big plunge.

Note: You do need to upgrade the global package to use v4, but v3 will still work for each local project where needed.

Installing gulp 4 globally

You will need to remove your current gulp global package before installing v4 in order to do an upgrade.

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

$ npm rm -g gulp
$ npm install -g gulp-cli

This command removes your current global package and installs v4 from the gulp-cli 4.0 branch.

Make sure you don't get any errors from the first command before you type the second. Depending on your set-up, you may need to run them with sudo.

To verify what version you have installed globally, you can run the below command (and should see a similar output)

$ gulp -v
CLI version 1.2.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 uninstall gulp --save-dev
$ npm install 'gulpjs/gulp.git#4.0' --save-dev

Following a similar technique to that of the global package, uninstall the local version, then install the upgrade.

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 1.2.1
Local version 4.0.0-alpha.2

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(){
    gulp.watch('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(){
    .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.

It's not that hard

It's not that difficult to update your gulp workflow to use version 4. Just remember - if you are sharing the project with other developers that they would need to upgrade to gulp v4 as well.

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!

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. @mikestreety


There is this videos with Addy Osmani explaining more things about to gulp 4 - https://www.youtube.com/watch?v=N42LQ2dLoA8 -

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() {
gulp.watch(config.src_dir + config.styles.src_dir + '**/*' + config.styles.extension, gulp.parallel('styles'));
gulp.watch(config.src_dir + config.pug.src_dir + '**/*.pug', gulp.parallel('templates'));
gulp.watch(config.src_dir + config.scripts.src_dir + '**/*.coffee', gulp.parallel('scripts'));
gulp.watch(config.src_dir + 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 'https://github.com/gulpjs/gulp.git#4.0' --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

Post a comment


Sign up to the Liquid Light newsletter

Subscribe to our Newsletter and stay up to date with all things web related. It's crammed full of useful articles, tips and knowledge, invaluable if you have a website or are starting a new web project.