Registry / data / glob
library13.0.6jsnpmunverified

The `glob` package provides a robust and highly performant implementation for matching files using shell-like patterns in JavaScript. It is widely considered one of the most correct and fastest glob implementations available, supporting standard glob features such as wildcards, brace expansion, and extended globs. The current stable version is 13.0.6, and it targets modern Node.js environments (v18, v20, >=v22). The library emphasizes correctness according to shell standards and offers both synchronous and asynchronous APIs, including stream-based operations and an advanced `Glob` object for optimized, re-usable pattern matching. A key differentiator is its `withFileTypes` option, which returns enhanced `Path` objects (similar to `fs.Dirent`) for rich file metadata access and manipulation, including custom sorting and filtering based on file stats. It is actively maintained with a regular release cadence for bug fixes and feature enhancements.

npm install glob
INSTALL
IMPORT
SIG · GLOB
G
glob
datajavascriptv13.0.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

glob
✓ import { glob } from 'glob'
✗ const glob = require('glob').glob
Primary asynchronous function for matching files, returns a Promise<string[]>. Named export, not default. CommonJS requires destructuring.
Glob
✓ import { Glob } from 'glob'
✗ import Glob from 'glob'
Class for creating reusable glob instances, useful for multiple walks or iterating. This is a named export, not a default import. CommonJS requires destructuring.
globSync
✓ import { globSync } from 'glob'
✗ require('glob').globSync()
Synchronous version of `glob`, returns `string[]`. Similar to `glob`, it's a named export and requires destructuring for CommonJS.

Demonstrates asynchronous glob matching, multi-pattern support, iteration with the `Glob` class, and retrieving detailed file type information with stats.

import { glob, Glob } from 'glob'; import { AbortSignal } from 'node:os'; // Or 'node-abort-controller' for older Node.js async function runGlobExamples() { // Find all JavaScript files, ignoring node_modules console.log('Finding JS files (excluding node_modules)...'); const jsFiles = await glob('**/*.js', { ignore: 'node_modules/**' }); console.log('Found JS files:', jsFiles.slice(0, 5), '...'); // Find images with multiple patterns console.log('\nFinding image files...'); const images = await glob(['css/*.{png,jpeg}', 'public/*.{png,jpeg}']); console.log('Found images:', images); // Using a Glob object for reusability and async iteration console.log('\nIterating with Glob object for "**/foo"...'); const g = new Glob('**/foo', {}); let fooCount = 0; for await (const file of g) { console.log('Found foo file:', file); fooCount++; if (fooCount > 3) break; // Limit output for example } if (fooCount === 0) console.log('No foo files found in this example.'); // Find files with detailed file types and stats, sorted by modification time console.log('\nFinding all files with stats, sorted by mtime...'); const results = await glob('**', { stat: true, withFileTypes: true, nodir: true }); const timeSortedFiles = results .sort((a, b) => a.mtimeMs - b.mtimeMs) .map(path => ({ path: path.fullpath(), mtime: new Date(path.mtimeMs).toLocaleTimeString() })) .slice(0, 5); console.log('Top 5 recently modified files:', timeSortedFiles); } runGlobExamples().catch(console.error);
Debug
Known issues
gotchaThe npm package name is `glob`, not `node-glob`. The `node-glob` package is a different, abandoned project. Installing or referencing `node-glob` will lead to using an outdated and unmaintained library.
fix
Always use `npm install glob` and `import { ... } from 'glob'` or `require('glob')`.
affects: >=1.0.0
breakingPrevious major versions might have used different argument signatures or returned different types. For instance, `glob.sync` might have been a direct property on the main `glob` export in older versions, which is not the case in v13.
fix
Consult the `glob` v13 documentation for current API signatures and return types. Migrate to named exports for all functions (`glob`, `globSync`, `globStream`, etc.) and the `Glob` class.
affects: <13.0.0
gotchaWhen using `async`/`await` with `glob` (the default asynchronous function), ensure your code is within an `async` function or top-level `await` is enabled, otherwise, you'll receive a `Promise` instead of the resolved file list.
fix
Wrap `await glob(...)` calls in an `async` function or ensure your environment supports top-level `await`.
affects: >=7.0.0
gotchaThe `ignore` option can accept a string, an array of strings, or an object with `ignored` and/or `childrenIgnored` functions for custom ignore logic. Misunderstanding this flexibility can lead to files not being ignored as expected or performance issues with complex custom ignore functions.
fix
Review the documentation for the `ignore` option. For simple patterns, use string/array. For advanced filtering, ensure your `ignored` and `childrenIgnored` functions are efficient and correctly handle `Path` objects if `withFileTypes` is used.
affects: >=10.0.0
Errors
Common errors & fixes
TypeError: glob is not a function
Attempting to call `require('glob')()` directly or incorrect destructuring in CommonJS.
fix
For CommonJS, use `const { glob } = require('glob');` then call `glob(...)`. For ESM, use `import { glob } from 'glob';`.
SyntaxError: await is only valid in async functions and the top level bodies of modules
Using `await glob(...)` outside an `async` function or a module with top-level await enabled.
fix
Define an `async` function and call `glob` inside it, or enable top-level await in your Node.js environment (requires Node.js 14+ and ESM modules).
Error: EMFILE: too many open files, open '...'
Globbing a very large number of files on systems with low file descriptor limits, especially with `stat: true`.
fix
Increase your system's file descriptor limit (e.g., `ulimit -n 4096` on Unix-like systems) or use `globStream` for memory efficiency and to avoid opening too many files simultaneously.
Upgrade
Version history
13.0.6latest on npm
Audit
Dependencies
path-scurryrequiredUsed internally for path manipulation and directory traversal, especially when `withFileTypes` is enabled, providing enhanced `Path` objects.
Agent activity
8 hits · last 30 days
node
8
Resources
glob — npm install glob · libregistry