fast-glob: a Node.js glob library with a Promise, sync and stream API

What fast-glob solves, and who ends up depending on it

Walking a directory tree and filtering by name is a small problem that turns into a large one once the tree is deep, the patterns overlap, and some entries are symlinks that point at themselves. fast-glob exists to do that walk and return the pathnames that matched a set of patterns, using rules close to those of the Unix Bash shell with some simplifications. The README is explicit that results come back in arbitrary order, which tells you the library optimises for getting matches out rather than for presenting them in a stable sequence.

The audience is Node.js code that needs to enumerate files: build tools, test runners, linters, asset pipelines, anything that has to answer the question of which files in a project match a shape. The package ships three entry points for the same matching engine, so a caller can pick the one that fits the surrounding code rather than adapting the surrounding code to the library.

How the matching engine is put together

The dependency list in package.json shows the division of labour. Pattern matching is delegated to micromatch, with picomatch types alongside it. Directory traversal is delegated to @nodelib/fs.walk, with @nodelib/fs.stat for stat calls. glob-parent computes the base directory of a pattern, and merge2 combines multiple streams. fast-glob itself is the layer that turns a pattern list into tasks, runs the walk, and merges the results.

That task model is exposed through the generateTasks helper, which returns the internal representation of patterns grouped by base directory. The README shows the output for the pattern '*': a single task with base '.', a dynamic flag set to true, and the pattern listed under both patterns and positive, with an empty negative array. Grouping by base directory is what lets the library start several walks instead of one walk from the root.

The README also states a rule that catches people out: the package does not respect the order of patterns. All negative patterns are applied first, and only then the positive ones. If you need a particular order in the output, the README points at sorting or splitting the calls. That is a deliberate simplification, and it means a pattern list is a set of constraints rather than a sequence of operations.

Installing fast-glob and running a first match

The README gives a single install command. It installs the package into the current project and adds it to the dependencies in package.json.

npm install fast-glob

The asynchronous API returns a Promise that resolves to an array of matching entries. The README's example passes two patterns and sets dot to true so that the leading-dot file is not skipped by the default hidden-file rule.

import * as fg from 'fast-glob';

const entries = await fg.glob(['.editorconfig', '**/index.js'], { dot: true });

// ['.editorconfig', 'services/index.js']

The same call has a synchronous form, globSync, which returns the array directly. It is the one to reach for in a script that has no reason to be asynchronous.

import * as fg from 'fast-glob';

const entries = fg.globSync(['.editorconfig', '**/index.js'], { dot: true });

For large result sets, globStream returns a ReadableStream that emits a data event per matching entry, and the README shows it consumed with for await. Note that the package is type: module and exports ./out/index.js, so the import form above is the documented one. Also check the engines field before installing: package.json sets it to ^22.13.0 || >=24.

Order, hidden files and symlinks: the sharp edges

Arbitrary order is the first thing to design around. If two runs of the same pattern list have to produce identical output, say for a cache key or a snapshot file, sort the result yourself. The README says exactly this, and it is not a defect so much as a consequence of the parallel walk.

The second edge is pattern precedence. Because negative patterns are applied before positive ones, a list like ['src/**/*.js', '!src/vendor/**'] behaves as you expect, but a list where a later positive pattern is meant to re-include something an earlier negative pattern removed will not work the way a shell would treat it. Splitting the call is the documented escape hatch.

The third edge is the default hidden-file rule. An asterisk matches everything except slashes and hidden files, meaning names starting with a dot. The README's own example sets dot to true to pick up .editorconfig, which is the clearest signal that this default will surprise anyone globbing a repository root. There are also options that change traversal behaviour rather than matching, including followSymbolicLinks, throwErrorOnBrokenSymbolicLink and errorFilter, so a tree containing broken symlinks can either fail loudly or be tolerated depending on how those are set.

Where fast-glob is the wrong tool

fast-glob is a Node.js package. The related searches include "Fast glob python", and the answer is that this repository is not that. There is no Python binding in the repository, and the package.json declares a Node.js engine range. If your pipeline is written in Python, you need a different library entirely.

It is also the wrong tool when you do not actually need a walk. If a build step knows the exact list of files it cares about, enumerating the directory and matching patterns adds a filesystem traversal and a pattern compile for no benefit. The same applies when the set of files is already in memory, for instance from a previous glob call or from a module graph.

Finally, the engine range is a real constraint rather than a formality. A project pinned to an older Node.js line cannot install the current version without changing that pin. The alternative is to stay on the 3.x line, whose last release listed here is 3.3.3 from 2025-01-05.

fast-glob against node-glob and the smaller glob packages

The README has a FAQ entry asking whether the package is compatible with node-glob, and the related searches pair the two names directly. The difference in approach is architectural. node-glob is the long-standing reference implementation whose behaviour the Unix shell comparison is usually measured against. fast-glob borrows micromatch for pattern semantics and @nodelib/fs.walk for traversal, then layers its own task grouping on top. That is why the README can promise three API shapes over one engine and an object mode that returns more than strings.

Against a smaller, newer glob package, the trade is weight. fast-glob pulls in micromatch, glob-parent, merge2 and two @nodelib packages. A minimal matcher will have fewer dependencies but a narrower pattern syntax. The README lists what the micromatch-backed syntax buys: POSIX character classes, extended globs, bash-style brace expansions, regexp character classes and regex groups. If your patterns stay at the level of * and **, you are paying for features you may not use.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-22. The release history is uneven: 3.3.1 in July 2023, 3.3.2 in November 2023, then 3.3.3 in January 2025, while package.json on master already carries version 4.0.0 with a raised engine range and a switch to type: module. The practical reading is that the 3.x line is the stable published line and 4.x is the change to plan for.

That upgrade is not a version bump you can take casually. Moving from 3.x to 4.x changes the module format, so a CommonJS require of fast-glob will need attention, and the engine range rises to ^22.13.0 || >=24. The package.json also lists fast-glob-v3 as a dev dependency aliased to fast-glob@^3.3.3, which indicates the project keeps the previous major around for comparison in its own tests rather than as a supported entry point for consumers.

The licence is MIT, declared in both the LICENSE file at the repository root and the license field of package.json. MIT permits use, modification and redistribution provided the copyright notice and permission notice are retained. That is a statement about the licence text, not advice about your situation; if your organisation has rules about dependency licences, the file to read is LICENSE.

Editorial conclusion

Adopt fast-glob if you are on Node.js 22.13.0 or newer and want one pattern engine that covers async, sync and stream reads, with object mode and stats when you need more than path strings. Do not adopt it if you are pinned to an older Node.js line, since the current package sets engines to ^22.13.0 || >=24, or if you need results in a deterministic order, because the README states that results are returned in arbitrary order and that negative patterns are applied before positive ones regardless of the order you pass them. Before committing, run the helper generateTasks on your own pattern list and check the task boundaries it reports, and confirm on your target runtime that the installed version is the one whose API you coded against.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mrmlnc/fast-glob on GitHub
4. README
5. Releases