Guide · Open source

How to use gulp: install, write a gulpfile and run tasks

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

gulp is an open-source build automation toolkit for JavaScript projects, released under the MIT licence. You describe your work as tasks in a gulpfile.js, such as compiling styles, minifying scripts or cleaning a folder, and gulp runs them in series or in parallel. This guide shows how to install it, write a gulpfile, run tasks, watch files and rebuild only what changed.

gulpgulpjs/gulp · ★ 32.9k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Node.js and npm are available on your machine. The README does not state a Node.js version, so confirm requirements in the Quick Start guide.
2Install gulp-cli globally. Run npm install --global gulp-cli to put the gulp command on your system.
3Add gulp to your project. Install the gulp package in your project so your gulpfile can require it.
4Create a gulpfile.js. Write plain JavaScript functions for each task and export them.
5Add plugins for each step. Install plugins such as gulp-less or gulp-uglify and pipe files through them inside a task.
6Run and watch. Run gulp to execute the default task, or run gulp watch to rerun tasks when files change.

What gulp is and who it suits

gulp describes itself as a streaming build system and a toolkit for automating time-consuming tasks in a development workflow. It works by passing files through a stream of plugins, and a task can run any npm package.

It suits front-end developers who want to automate compiling, minifying and bundling assets, and teams with a repeatable build step written as plain JavaScript functions. It is a poor fit if you only need a bundler for modern modules, if you want zero configuration, or if you need a graphical tool.

Good fit: automating compiling, minifying and bundling assets
Good fit: build steps written as plain JavaScript functions
Good fit: projects already using npm with a small API to learn
Less suited: a dedicated bundler for modern JavaScript modules
Less suited: zero-configuration setups or graphical tools

Install gulp with npm

gulp is installed with a package manager. The prerequisites named in the README are Node.js and npm. The README does not state a minimum Node.js version, so check the Quick Start guide linked from the project before installing.

To install the command-line tool globally, run the command below. The README points to the Quick Start guide at gulpjs.com for installation details.

npm install --global gulp-cli

Write a gulpfile.js with tasks

A gulpfile.js is an ordinary Node.js file in your project. Each task is a plain function. Inside a task you use gulp.src to read files, pipe them through plugins such as gulp-less or gulp-uglify, and finish with gulp.dest to write the output.

The sample below defines a clean task, a styles task that compiles Less and minifies CSS, and a scripts task that runs Babel and Uglify. It exports the tasks so you can run them by name, and sets a default task.

Each task must return a stream, a Promise, or accept a callback and call it. The sample also shows that a gulpfile is just another Node program, so any npm package can be used inside a task.

Use gulp.src(glob) to select source files
Pipe files through plugins with .pipe(plugin())
Write results with gulp.dest(folder)
Use exports to declare tasks; exports.default runs when you type gulp with no task name

var gulp = require('gulp');
var less = require('gulp-less');
var babel = require('gulp-babel');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var rename = require('gulp-rename');
var cleanCSS = require('gulp-clean-css');
var del = require('del');

var paths = {
  styles: {
    src: 'src/styles/**/*.less',
    dest: 'assets/styles/'
  },
  scripts: {
    src: 'src/scripts/**/*.js',
    dest: 'assets/scripts/'
  }
};

function clean() {
  return del([ 'assets' ]);
}

function styles() {
  return gulp.src(paths.styles.src)
    .pipe(less())
    .pipe(cleanCSS())
    .pipe(rename({
      basename: 'main',
      suffix: '.min'
    }))
    .pipe(gulp.dest(paths.styles.dest));
}

function scripts() {
  return gulp.src(paths.scripts.src, { sourcemaps: true })
    .pipe(babel())
    .pipe(uglify())
    .pipe(concat('main.min.js'))
    .pipe(gulp.dest(paths.scripts.dest));
}

function watch() {
  gulp.watch(paths.scripts.src, scripts);
  gulp.watch(paths.styles.src, styles);
}

var build = gulp.series(clean, gulp.parallel(styles, scripts));

exports.clean = clean;
exports.styles = styles;
exports.scripts = scripts;
exports.watch = watch;
exports.build = build;
exports.default = build;

Run tasks in series or in parallel

Use gulp.series to run tasks one after another and gulp.parallel to run them at the same time. In the sample, the build task first runs clean, then runs styles and scripts in parallel. Compose these two functions to control the order of your build.

Once the gulpfile is written, run gulp with a task name to execute that task, or run gulp alone to execute the default task.

gulp.series(a, b): runs a, then b
gulp.parallel(a, b): runs a and b together
gulp: runs the default task
gulp styles: runs only the styles task

gulp

Watch files and rebuild only changed files

The watch task uses gulp.watch to rerun a task when matching files change. The sample's watch task reruns scripts when files in src/scripts change and reruns styles when files in src/styles change.

For tasks that process many files, such as images, you can skip unchanged files between runs with the since option of gulp.src and gulp.lastRun. The README notes that run times are kept in memory, so they are lost when gulp exits, and the time saving applies only when the images task runs again during a watch.

Run the watch task with: gulp watch
Use { since: gulp.lastRun(task) } in gulp.src to skip unchanged files
Incremental timing is held in memory and resets when gulp exits

function images() {
  return gulp.src(paths.images.src, {since: gulp.lastRun(images)})
    .pipe(imagemin())
    .pipe(gulp.dest(paths.images.dest));
}

Use ES modules in your gulpfile

gulp loads a wrapper for ESM code, so you can name your gulpfile gulpfile.mjs or set "type": "module" in your package.json. The sample below is the same build written with import and export. It uses named imports from gulp and exports tasks with export const or export function.

The README also shows that export as can rename a task, for example exporting a watchFiles function as watch.

Name the file gulpfile.mjs, or set "type": "module" in package.json
Use import { src, dest, watch } from 'gulp'
Export tasks with export const or export function

import { src, dest, watch } from 'gulp';
import less from 'gulp-less';
import babel from 'gulp-babel';
import concat from 'gulp-concat';
import uglify from 'gulp-uglify';
import rename from 'gulp-rename';
import cleanCSS from 'gulp-clean-css';
import {deleteAsync} from 'del';

export const clean = () => deleteAsync([ 'assets' ]);

export function styles() {
  return src('src/styles/**/*.less')
    .pipe(less())
    .pipe(cleanCSS())
    .pipe(rename({ basename: 'main', suffix: '.min' }))
    .pipe(dest('assets/styles/'));
}

function watchFiles() {
  watch('src/scripts/**/*.js', scripts);
  watch('src/styles/**/*.less', styles);
}
export { watchFiles as watch };

What people use it for

Compile Less stylesheets and minify the output into an assets folder
Transpile and minify JavaScript files and concatenate them into one bundle
Clean a build folder before each build with a clean task
Rerun the style and script tasks automatically while you edit files
Skip unchanged images during a watch session using gulp.lastRun

Frequently asked questions

How do I install gulp?

The README says to install the command-line tool globally with npm install --global gulp-cli. It links to the Quick Start guide at gulpjs.com for installation details. You also need Node.js and npm.

What do I need to run gulp?

The README lists Node.js and npm as prerequisites. It does not state a minimum Node.js version, so check the Quick Start guide before you install.

Is gulp free to use?

gulp is released under the MIT licence, as stated in the project information. You can use, modify and distribute it under the terms of that licence.

What is the difference between gulp and webpack?

gulp is a build automation toolkit where you write tasks that pass files through plugins. The README does not describe gulp as a bundler, so for bundling modern JavaScript modules a dedicated bundler such as webpack or Rollup may fit better.

Can gulp watch files and rebuild only what changed?

Yes. gulp.watch reruns a task when matching files change, and the since option with gulp.lastRun skips unchanged files. The README notes that these run times are kept in memory and reset when gulp exits.

Are there alternatives to gulp?

The project lists Grunt, webpack, Rollup and esbuild as comparable projects. Choose based on whether you need task automation, module bundling or fast compilation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

gulp suits front-end developers and teams who want build steps written as plain JavaScript functions with a small API and a large plugin ecosystem. If you mainly need to bundle modern JavaScript modules, or you want a tool that needs no hand-written configuration, a dedicated bundler or a zero-config tool is likely a better choice.

Install options & downloads