# gulp-imagemin for Gulp image compression

> gulp-imagemin adds PNG, JPEG, GIF, and SVG optimization to Gulp streams. It is a focused adapter for imagemin, with bundled defaults and plugin-level control for image build pipelines.

**sindresorhus/gulp-imagemin** — Minify PNG, JPEG, GIF and SVG images

- Repository: https://github.com/sindresorhus/gulp-imagemin
- Stars: 1,901 · Forks: 155
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/sindresorhus-gulp-imagemin

## Why gulp-imagemin belongs in a Gulp build

gulp-imagemin solves a focused build-pipeline problem: compressing common web image formats while files move through Gulp. It targets PNG, JPEG, GIF, and SVG assets, so it is aimed at developers who maintain a Gulp build for a website or another JavaScript project. It is not presented as a general image editor, a standalone image-processing command, or a replacement for a complete asset pipeline. Its central interface is a Gulp stream.

The basic data path is straightforward. `gulp.src()` selects files, the image-minification transform processes supported files, and `gulp.dest()` writes the resulting stream. That design explains both its usefulness and its limitation. A project already using Gulp can place image compression beside other build operations without writing a separate image-processing application. A project without Gulp would first need to introduce Gulp or choose a different integration, because the README does not document a command-line interface for this package.

Compression behavior also depends on format. The documented defaults pair GIF with `gifsicle`, JPEG with `mozjpeg`, PNG with `optipng`, and SVG with `svgo`. The README describes GIF, PNG, and SVG compression as lossless, while JPEG uses lossy compression. That distinction matters for photographs, logos, diagrams, and any asset where byte changes must not alter the intended rendering.

## How gulp-imagemin processes selected image files

The package is an adapter around `imagemin`. Files selected by Gulp enter the transform, supported files are processed by configured imagemin plugins, and optimized Vinyl files continue toward the destination. Unsupported files are ignored. This makes a broad source glob convenient, but it also means that passing a file through the transform does not prove that the file was optimized.

The API is `imagemin(plugins?, options?)`. The default plugin list is `[gifsicle(), mozjpeg(), optipng(), svgo()]`. Supplying a custom `plugins` array completely replaces the default list. For example, an array containing only `svgo()` does not retain PNG, JPEG, or GIF optimization. If a project uses custom plugins while still needing a bundled optimizer, it must include that optimizer explicitly.

The package exposes two reporting options. `verbose` defaults to `false`. When enabled, it logs information for every image, including whether an image was already optimized or how many bytes were saved. `silent` defaults to `false` and suppresses the summary count of minified images when enabled. The README also states that the `--silent` command-line flag can enable silent behavior when the option is not already specified. These controls affect reporting, not compression behavior.

## Installing gulp-imagemin and creating a first task

The README gives one installation command. It installs the package as a development dependency, which fits its role as a build-time optimizer rather than a runtime dependency. Run it in the project that already has its Gulp setup and package manifest.

```bash
npm install --save-dev gulp-imagemin
```

After installation, add the documented imports to the Gulp task. The example uses ES module imports because `package.json` sets `"type": "module"`. It selects files from `src/images/*`, passes them through `imagemin()`, and writes them to `dist/images`.

```js
import gulp from 'gulp';
import imagemin from 'gulp-imagemin';

export default () => (
	gulp.src('src/images/*')
		.pipe(imagemin())
		.pipe(gulp.dest('dist/images'))
);
```

The README does not give the exact command for executing this task, so no command is added here. The project supplies that command through its own Gulp workflow. The package manifest requires Node.js `>=18` and declares Gulp `>=4` as an optional peer dependency. A project must therefore provide a compatible Gulp installation to use this example.

## What the first Gulp image task produces

The source glob controls which files enter the transform. With the documented default plugins, PNG files can pass through `optipng()`, JPEG files through `mozjpeg()`, GIF files through `gifsicle()`, and SVG files through `svgo()`. The destination directory receives the stream produced by Gulp. Unsupported files are ignored, so a glob containing several formats does not imply that every file is minified.

Verbose mode provides the clearest way to inspect what happened. The README shows output identifying an image that was already optimized and another image that saved `91 B - 0.4%`. Those lines are examples, not expected results for every project. Actual savings depend on the source file and the selected optimizer settings.

```text
gulp-imagemin: ✔ image1.png (already optimized)
gulp-imagemin: ✔ image2.png (saved 91 B - 0.4%)
```

The `silent` option defaults to `false`. Enabling it suppresses the number of images that were minified. The README states that `--silent` can enable this behavior from the command line when the option is not already specified. Neither option changes the optimizer list.

## Configuring gifsicle, mozjpeg, optipng, and svgo

Custom configuration is available when the default settings do not match a project's asset policy. The README imports `gifsicle`, `mozjpeg`, `optipng`, and `svgo` from `gulp-imagemin`, then passes them as an explicit plugin array. Keeping all four entries matters because a custom array replaces the complete default array.

```js
import imagemin, {gifsicle, mozjpeg, optipng, svgo} from 'gulp-imagemin';

// …
.pipe(imagemin([
	gifsicle({interlaced: true}),
	mozjpeg({quality: 75, progressive: true}),
	optipng({optimizationLevel: 5}),
	svgo({
		plugins: [
			{
				name: 'removeViewBox',
				active: true
			},
			{
				name: 'cleanupIDs',
				active: false
			}
		]
	})
]))
// …
```

These options change encoder behavior rather than merely changing output logs. The documented `quality: 75` and `progressive: true` settings control JPEG output, while `interlaced: true` controls GIF output. The SVGO settings enable `removeViewBox` and disable `cleanupIDs`. Projects should compare representative files after changing these values, especially when SVGs are reused by other systems or when JPEG quality affects visual deliverables.

The second argument configures gulp-imagemin itself. The README shows `verbose: true` alongside a custom `svgo()` plugin list. That example does not include the other default optimizers, so it is a partial configuration rather than a drop-in equivalent to the default call.

## WebP, ignored files, and wrong-tool cases

The repository includes a `fixture.webp` file, but the README lists PNG, JPEG, GIF, and SVG as the formats handled by the bundled optimizers. WebP is not included in that documented default list. The package also states that unsupported files are ignored. Those facts leave WebP handling unconfirmed. A project that depends on WebP optimization should not assume that this package processes it correctly based only on the repository fixture.

A mixed source glob can therefore hide a coverage issue. If a directory contains supported images alongside unsupported assets, the transform may process the first group and ignore the second. This is useful when the glob is intended to contain only assets handled by the plugin, but it can be surprising when the pipeline is expected to copy every selected file. The README does not document a separate copy-through task or a general passthrough guarantee.

gulp-imagemin is also the wrong tool for a project that does not use Gulp. Direct use of `imagemin` is the more relevant alternative when image optimization must be called from another pipeline. The README links to `imagemin` for the underlying API and directs output issues there, but it does not provide a complete standalone setup tutorial. That makes the architecture, not the format list, the deciding factor.

## Maintenance, compatibility, and upgrade cost

The repository is not archived. Its last push was on 2026-09-18, and recent releases include `v9.2.0` on 2025-11-11, `v9.1.0` on 2024-05-05, and `v9.0.0` on 2023-11-02. The current package manifest declares version `9.2.0`, uses the `type` module format, exports `index.js`, and requires Node.js `>=18`. Gulp `>=4` appears in `peerDependencies`, with peer metadata marking Gulp as optional.

The four optimizer packages are listed as optional dependencies: `imagemin-gifsicle`, `imagemin-mozjpeg`, `imagemin-optipng`, and `imagemin-svgo`. The manifest includes only `index.js` in its published `files` list. Upgrading involves checking Node.js compatibility, Gulp compatibility, ES module syntax, dependency installation, and changes in optimizer output. The README does not provide a migration guide.

The package license is MIT. That identifies the declared license of this project, but it is not legal advice and does not replace reviewing dependency licenses. The practical upgrade cost is output-related: optimizer versions and settings can change compressed bytes. A version change should be checked against representative PNG, JPEG, GIF, and SVG assets before it replaces an established build.

## Choosing gulp-imagemin over direct imagemin use

The direct alternative is `imagemin` without the Gulp adapter. Both approaches use imagemin plugins and share the same core compression model. The difference is orchestration. gulp-imagemin is built to receive and emit Gulp Vinyl streams, while direct imagemin use can be called from a different JavaScript pipeline. The README directs issues about optimizer output to the imagemin issue tracker, which reflects that separation between the adapter and the underlying optimization layer.

Choose gulp-imagemin when source selection, optimization, and destination writing already belong in a Gulp task. Choose direct imagemin integration when image compression must be isolated from Gulp or embedded in another build system. Neither approach is automatically preferable. gulp-imagemin reduces stream boilerplate for existing Gulp users, but it adds a Gulp-specific dependency and leaves the exact supported formats dependent on the selected plugins. The project should match the existing build architecture rather than be selected for a generic promise of smaller images.

## Conclusion

gulp-imagemin suits Node.js projects that already build through Gulp and want image optimization in the same stream. It is a poor fit for workflows without Gulp, undocumented WebP handling, or teams that need different orchestration. Verify Node.js 18 or later, a compatible Gulp 4 or newer installation, and representative image output before adopting it. With those boundaries confirmed, the package is a practical Gulp-specific image compression layer under the MIT license.

## FAQ

### Which image formats does gulp-imagemin compress by default?

Its documented defaults use `gifsicle()` for GIF, `mozjpeg()` for JPEG, `optipng()` for PNG, and `svgo()` for SVG. Unsupported files are ignored.

### What Node.js and Gulp versions does gulp-imagemin require?

The package manifest requires Node.js `>=18` and declares Gulp `>=4` as an optional peer dependency. A project using the Gulp task must provide a compatible installed Gulp version.

### Do custom imagemin plugins keep gulp-imagemin's default optimizers?

No. A custom `plugins` array completely overwrites the default array, so any required default optimizers must be included explicitly.

### Does the README document WebP optimization?

No. It lists PNG, JPEG, GIF, and SVG as the bundled formats. The repository contains a `fixture.webp` file, but the README does not document how WebP is handled.

## Sources

- [Issues](https://github.com/sindresorhus/gulp-imagemin/issues)
- [License: MIT](https://github.com/sindresorhus/gulp-imagemin/blob/main/LICENSE)
- [README](https://github.com/sindresorhus/gulp-imagemin/blob/main/README.md)
- [Releases](https://github.com/sindresorhus/gulp-imagemin/releases)
- [sindresorhus/gulp-imagemin on GitHub](https://github.com/sindresorhus/gulp-imagemin)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sindresorhus-gulp-imagemin