# gulp-filter

> Filter files in a `vinyl` stream

Latest version **10.0.0** (published 2026-04-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-filter
pnpm add gulp-filter
yarn add gulp-filter
bun add gulp-filter
```

## Health

**Score 58/100 (C)** — status: active.

Positive: has types package; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 10.0.0 |
| Published | 2026-04-17 |
| First published | 2014-01-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/gulp-filter) |
| Module format | ESM |
| Node | >=22 |
| Dependencies | 5 |
| Unpacked size | 7.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 313 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | gulpplugin, filter, ignore, file, files, match, minimatch, glob, globbing, vinyl |

## Links

- npm: https://www.npmjs.com/package/gulp-filter
- Repository: https://github.com/sindresorhus/gulp-filter
- Homepage: https://github.com/sindresorhus/gulp-filter#readme
- Issues: https://github.com/sindresorhus/gulp-filter/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/gulp-filter

## Dependencies (5)

- [slash](https://npm.io/package/slash.md) ^5.1.0
- [multimatch](https://npm.io/package/multimatch.md) ^8.0.0
- [plugin-error](https://npm.io/package/plugin-error.md) ^2.0.1
- [to-absolute-glob](https://npm.io/package/to-absolute-glob.md) ^3.0.0
- [easy-transform-stream](https://npm.io/package/easy-transform-stream.md) ^1.0.1

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 10.0.0 (latest) — 2026-04-17
- 9.0.1 — 2023-11-15
- 9.0.0 — 2023-11-02
- 8.0.0 — 2023-07-22
- 7.0.0 — 2021-04-24
- 6.0.0 — 2019-05-28
- 5.1.0 — 2017-12-29
- 5.0.1 — 2017-08-03
- 5.0.0 — 2017-01-10
- 4.0.0 — 2016-03-01
- 3.0.1 — 2015-08-21
- 3.0.0 — 2015-07-27
- 2.0.2 — 2015-02-16
- 2.0.1 — 2015-02-08
- 2.0.0 — 2014-12-22
- … 13 more at https://npm.io/package/gulp-filter/versions

## README

# gulp-filter

> Filter files in a [`vinyl`](https://github.com/gulpjs/vinyl) stream

Enables you to work on a subset of the original files by filtering them using glob patterns. When you're done and want all the original files back, you just use the `restore` stream.

## Install

```sh
npm install --save-dev gulp-filter
```

## Usage

### Filter only

You may want to just filter the stream content:

```js
import gulp from 'gulp';
import uglify from 'gulp-uglify';
import filter from 'gulp-filter';

export default () => {
	// Create filter instance inside task function
	const f = filter(['**', '!*src/vendor']);

	return gulp.src('src/**/*.js')
		// Filter a subset of the files
		.pipe(f)
		// Run them through a plugin
		.pipe(uglify())
		.pipe(gulp.dest('dist'));
};
```

### Restoring filtered files

```js
import gulp 'gulp';
import uglify 'gulp-uglify';
import filter 'gulp-filter';

export default () => {
	// Create filter instance inside task function
	const f = filter(['**', '!*src/vendor'], {restore: true});

	return gulp.src('src/**/*.js')
		// Filter a subset of the files
		.pipe(f)
		// Run them through a plugin
		.pipe(uglify())
		// Bring back the previously filtered out files (optional)
		.pipe(f.restore)
		.pipe(gulp.dest('dist'));
};
```

### Multiple filters

By combining and restoring different filters you can process different sets of files with a single pipeline.

```js
import gulp from 'gulp';
import less from 'gulp-less';
import concat from 'gulp-concat';
import filter from 'gulp-filter';

export default () => {
	const jsFilter = filter('**/*.js', {restore: true});
	const lessFilter = filter('**/*.less', {restore: true});

	return gulp.src('assets/**')
		.pipe(jsFilter)
		.pipe(concat('bundle.js'))
		.pipe(jsFilter.restore)
		.pipe(lessFilter)
		.pipe(less())
		.pipe(lessFilter.restore)
		.pipe(gulp.dest('out/'));
};
```

### Restore as a file source

You can restore filtered files in a different place and use it as a standalone source of files (ReadableStream). Setting the `passthrough` option to `false` allows you to do so.

```js
import gulp 'gulp';
import uglify 'gulp-uglify';
import filter 'gulp-filter';

export default () => {
	const f = filter(['**', '!*src/vendor'], {restore: true, passthrough: false});

	const stream = gulp.src('src/**/*.js')
		// Filter a subset of the files
		.pipe(f)
		// Run them through a plugin
		.pipe(uglify())
		.pipe(gulp.dest('dist'));

	// Use filtered files as a gulp file source
	f.restore.pipe(gulp.dest('vendor-dist'));

	return stream;
};
```

## API

### filter(pattern, options?)

Returns a [transform stream](https://nodejs.org/api/stream.html#stream_class_stream_transform) with a [.restore](#optionsrestore) property.

#### pattern

Type: `string | string[] | Function`

Accepts a string/array with globbing patterns which are run through [multimatch](https://github.com/sindresorhus/multimatch).

If you supply a function, you'll get a [`vinyl` file object](https://github.com/wearefractal/vinyl#file) as the first argument and you're expected to return a boolean of whether to include the file:

```js
filter(file => /unicorns/.test(file.path));
```

#### options

Type: `object`

Accepts [`minimatch` options](https://github.com/isaacs/minimatch#options).

*Note:* Set `dot: true` if you need to match files prefixed with a dot, for example, `.gitignore`.

##### restore

Type: `boolean`\
Default: `false`

Restore filtered files.

##### passthrough

Type: `boolean`\
Default: `true`

When set to `true`, filtered files are restored with a `stream.PassThrough`, otherwise, when set to `false`, filtered files are restored as a `stram.Readable`.

When the stream is a `stream.Readable`, it ends by itself, but when it's `stream.PassThrough`, you are responsible of ending the stream.

---
_Source: https://npm.io/package/gulp-filter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._