Need help with node-glob?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

7.2K Stars 455 Forks Other 456 Commits 122 Opened issues


glob functionality for node.js

Services available


Need anything else?

Contributors list


Match files using the patterns the shell uses, like stars and stuff.

Build Status Build Status Coverage Status

This is a glob implementation in JavaScript. It uses the

library to do its matching.

a fun cartoon logo made of glob characters


Install with npm

npm i glob
var glob = require("glob")

// options is optional glob("*/.js", options, function (er, files) { // files is an array of filenames. // If the nonull option is set, and nothing // was found, then files is ["*/.js"] // er is an error object or null. })

Glob Primer

"Globs" are the patterns you type when you do stuff like

ls *.js
on the command line, or put
in a

Before parsing the path part patterns, braced sections are expanded into a set. Braced sections start with

and end with
, with any number of comma-delimited sections within. Braced sections may contain slash characters, so
would expand into

The following characters have special magic meaning when used in a path portion:

  • *
    Matches 0 or more characters in a single path portion
  • ?
    Matches 1 character
  • [...]
    Matches a range of characters, similar to a RegExp range. If the first character of the range is
    then it matches any character not in the range.
  • !(pattern|pattern|pattern)
    Matches anything that does not match any of the patterns provided.
  • ?(pattern|pattern|pattern)
    Matches zero or one occurrence of the patterns provided.
  • +(pattern|pattern|pattern)
    Matches one or more occurrences of the patterns provided.
  • *(a|b|c)
    Matches zero or more occurrences of the patterns provided
  • @(pattern|pat*|pat?erN)
    Matches exactly one of the patterns provided
  • **
    If a "globstar" is alone in a path portion, then it matches zero or more directories and subdirectories searching for matches. It does not crawl symlinked directories.


If a file or directory path portion has a

as the first character, then it will not match any glob pattern unless that pattern's corresponding path part also has a
as its first character.

For example, the pattern

would match the file at
. However the pattern
would not, because
does not start with a dot character.

You can make glob treat dots as normal characters by setting

in the options.

Basename Matching

If you set

in the options, and the pattern has no slashes in it, then it will seek for any file anywhere in the tree with a matching basename. For example,
would match

Empty Sets

If no matching files are found, then an empty array is returned. This differs from the shell, where the pattern itself is returned. For example:

$ echo a*s*d*f

To get the bash-style behavior, set the

in the options.

See Also:

glob.hasMagic(pattern, [options])


if there are any special characters in the pattern, and

Note that the options affect the results. If

is set in the options object, then
will not be considered a magic pattern. If the pattern has a brace expansion, like
then that is considered magical, unless
is set in the options.

glob(pattern, [options], cb)

  • pattern
    Pattern to be matched
  • options
  • cb
    • err
      {Error | null}
    • matches
      filenames found matching the pattern

Perform an asynchronous glob search.

glob.sync(pattern, [options])

  • pattern
    Pattern to be matched
  • options
  • return:
    filenames found matching the pattern

Perform a synchronous glob search.

Class: glob.Glob

Create a Glob object by instantiating the

var Glob = require("glob").Glob
var mg = new Glob(pattern, options, cb)

It's an EventEmitter, and starts walking the filesystem to find matches immediately.

new glob.Glob(pattern, [options], [cb])

  • pattern
    pattern to search for
  • options
  • cb
    Called when an error occurs, or matches are found
    • err
      {Error | null}
    • matches
      filenames found matching the pattern

Note that if the

flag is set in the options, then matches will be immediately available on the


  • minimatch
    The minimatch object that the glob uses.
  • options
    The options object passed in.
  • aborted
    Boolean which is set to true when calling
    . There is no way at this time to continue a glob search after aborting, but you can re-use the statCache to avoid having to duplicate syscalls.
  • cache
    Convenience object. Each field has the following possible values:
    • false
      - Path does not exist
    • true
      - Path exists
    • 'FILE'
      - Path exists, and is not a directory
    • 'DIR'
      - Path exists, and is a directory
    • [file, entries, ...]
      - Path exists, is a directory, and the array value is the results of
  • statCache
    Cache of
    results, to prevent statting the same path multiple times.
  • symlinks
    A record of which paths are symbolic links, which is relevant in resolving
  • realpathCache
    An optional object which is passed to
    to minimize unnecessary syscalls. It is stored on the instantiated Glob object, and may be re-used.


  • end
    When the matching is finished, this is emitted with all the matches found. If the
    option is set, and no match was found, then the
    list contains the original pattern. The matches are sorted, unless the
    flag is set.
  • match
    Every time a match is found, this is emitted with the specific thing that matched. It is not deduplicated or resolved to a realpath.
  • error
    Emitted when an unexpected error is encountered, or whenever any fs error occurs if
    is set.
  • abort
    is called, this event is raised.


  • pause
    Temporarily stop the search
  • resume
    Resume the search
  • abort
    Stop the search forever


All the options that can be passed to Minimatch can also be passed to Glob to change pattern matching behavior. Also, some have been added, or have glob-specific ramifications.

All options are false by default, unless otherwise noted.

All options are added to the Glob object, as well.

If you are running many

operations, you can pass a Glob object as the
argument to a subsequent operation to shortcut some
calls. At the very least, you may pass in shared
, and
options, so that parallel glob operations will be sped up by sharing information about the filesystem.
  • cwd
    The current working directory in which to search. Defaults to
  • root
    The place where patterns starting with
    will be mounted onto. Defaults to
    path.resolve(options.cwd, "/")
    on Unix systems, and
    or some such on Windows.)
  • dot
    files in normal matches and
    matches. Note that an explicit dot in a portion of the pattern will always match dot files.
  • nomount
    By default, a pattern starting with a forward-slash will be "mounted" onto the root setting, so that a valid filesystem path is returned. Set this flag to disable that behavior.
  • mark
    Add a
    character to directory matches. Note that this requires additional stat calls.
  • nosort
    Don't sort the results.
  • stat
    Set to true to stat all results. This reduces performance somewhat, and is completely unnecessary, unless
    is presumed to be an untrustworthy indicator of file existence.
  • silent
    When an unusual error is encountered when attempting to read a directory, a warning will be printed to stderr. Set the
    option to true to suppress these warnings.
  • strict
    When an unusual error is encountered when attempting to read a directory, the process will just continue on in search of other matches. Set the
    option to raise an error in these cases.
  • cache
    property above. Pass in a previously generated cache object to save some fs calls.
  • statCache
    A cache of results of filesystem information, to prevent unnecessary stat calls. While it should not normally be necessary to set this, you may pass the statCache from one glob() call to the options object of another, if you know that the filesystem will not change between calls. (See "Race Conditions" below.)
  • symlinks
    A cache of known symbolic links. You may pass in a previously generated
    object to save
    calls when resolving
  • sync
    glob.sync(pattern, opts)
  • nounique
    In some cases, brace-expanded patterns can result in the same file showing up multiple times in the result set. By default, this implementation prevents duplicates in the result set. Set this flag to disable that behavior.
  • nonull
    Set to never return an empty set, instead returning a set containing the pattern itself. This is the default in glob(3).
  • debug
    Set to enable debug logging in minimatch and glob.
  • nobrace
    Do not expand
    brace sets.
  • noglobstar
    Do not match
    against multiple filenames. (Ie, treat it as a normal
  • noext
    Do not match
    "extglob" patterns.
  • nocase
    Perform a case-insensitive match. Note: on case-insensitive filesystems, non-magic patterns will match by default, since
    will not raise errors.
  • matchBase
    Perform a basename-only match if the pattern does not contain any slash characters. That is,
    would be treated as equivalent to
    , matching all js files in all directories.
  • nodir
    Do not match directories, only files. (Note: to match only directories, simply put a
    at the end of the pattern.)
  • ignore
    Add a pattern or an array of glob patterns to exclude matches. Note:
    patterns are always in
    mode, regardless of any other settings.
  • follow
    Follow symlinked directories when expanding
    patterns. Note that this can result in a lot of duplicate references in the presence of cyclic links.
  • realpath
    Set to true to call
    on all of the results. In the case of a symlink that cannot be resolved, the full absolute path to the matched entry is returned (though it will usually be a broken symlink)
  • absolute
    Set to true to always receive absolute paths for matched files. Unlike
    , this also affects the values returned in the
  • fs
    File-system object with Node's
    API. By default, the built-in
    module will be used. Set to a volume provided by a library like
    to avoid using the "real" file-system.

Comparisons to other fnmatch/glob implementations

While strict compliance with the existing standards is a worthwhile goal, some discrepancies exist between node-glob and other implementations, and are intentional.

The double-star character

is supported by default, unless the
flag is set. This is supported in the manner of bsdglob and bash 4.3, where
only has special significance if it is the only thing in a path part. That is,
will match
, but
will not.

Note that symlinked directories are not crawled as part of a

, though their contents may match against subsequent portions of the pattern. This prevents infinite loops and duplicates and the like.

If an escaped pattern has no matches, and the

flag is set, then glob returns the pattern as-provided, rather than interpreting the character escapes. For example,
glob.match([], "\\*a\\?")
will return
rather than
. This is akin to setting the
option in bash, except that it does not resolve escaped pattern characters.

If brace expansion is not disabled, then it is performed before any other interpretation of the glob pattern. Thus, a pattern like

, which would not be valid in bash or zsh, is expanded first into the set of
, and those patterns are checked for validity. Since those two are valid, matching proceeds.

Comments and Negation

Previously, this module let you mark a pattern as a "comment" if it started with a

character, or a "negated" pattern if it started with a

These options were deprecated in version 5, and removed in version 6.

To specify things that should not match, use the



Please only use forward-slashes in glob expressions.

Though windows uses either

as its path separator, only
characters are used by this glob implementation. You must use forward-slashes only in glob expressions. Back-slashes will always be interpreted as escape characters, not path separators.

Results from absolute patterns such as

are mounted onto the root setting using
. On windows, this will by default result in

Race Conditions

Glob searching, by its very nature, is susceptible to race conditions, since it relies on directory walking and such.

As a result, it is possible that a file that exists when glob looks for it may have been deleted or modified by the time it returns the result.

As part of its internal implementation, this program caches all stat and readdir calls that it makes, in order to cut down on system overhead. However, this also makes it even more susceptible to races, especially if the cache or statCache objects are reused between glob calls.

Users are thus advised not to use a glob result as a guarantee of filesystem state in the face of rapid changes. For the vast majority of operations, this is never a problem.

Glob Logo

Glob's logo was created by Tanya Brassie. Logo files can be found here.

The logo is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.


Any change to behavior (including bugfixes) must come with a test.

Patches that fail tests or reduce performance will be rejected.

# to run tests
npm test

to re-generate test fixtures

npm run test-regen

to benchmark against bash/zsh

npm run bench

to profile javascript

npm run prof

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.