1:mod:`glob` --- Unix style pathname pattern expansion
2=====================================================
3
4.. module:: glob
5   :synopsis: Unix shell style pathname pattern expansion.
6
7**Source code:** :source:`Lib/glob.py`
8
9.. index:: single: filenames; pathname expansion
10
11--------------
12
13.. index::
14   single: * (asterisk); in glob-style wildcards
15   single: ? (question mark); in glob-style wildcards
16   single: [] (square brackets); in glob-style wildcards
17   single: ! (exclamation); in glob-style wildcards
18   single: - (minus); in glob-style wildcards
19   single: . (dot); in glob-style wildcards
20
21The :mod:`glob` module finds all the pathnames matching a specified pattern
22according to the rules used by the Unix shell, although results are returned in
23arbitrary order.  No tilde expansion is done, but ``*``, ``?``, and character
24ranges expressed with ``[]`` will be correctly matched.  This is done by using
25the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions in concert, and
26not by actually invoking a subshell.  Note that unlike :func:`fnmatch.fnmatch`,
27:mod:`glob` treats filenames beginning with a dot (``.``) as special cases.
28(For tilde and shell variable expansion, use :func:`os.path.expanduser` and
29:func:`os.path.expandvars`.)
30
31For a literal match, wrap the meta-characters in brackets.
32For example, ``'[?]'`` matches the character ``'?'``.
33
34
35.. seealso::
36   The :mod:`pathlib` module offers high-level path objects.
37
38
39.. function:: glob(pathname, *, root_dir=None, dir_fd=None, recursive=False)
40
41   Return a possibly-empty list of path names that match *pathname*, which must be
42   a string containing a path specification. *pathname* can be either absolute
43   (like :file:`/usr/src/Python-1.5/Makefile`) or relative (like
44   :file:`../../Tools/\*/\*.gif`), and can contain shell-style wildcards. Broken
45   symlinks are included in the results (as in the shell). Whether or not the
46   results are sorted depends on the file system.  If a file that satisfies
47   conditions is removed or added during the call of this function, whether
48   a path name for that file be included is unspecified.
49
50   If *root_dir* is not ``None``, it should be a :term:`path-like object`
51   specifying the root directory for searching.  It has the same effect on
52   :func:`glob` as changing the current directory before calling it.  If
53   *pathname* is relative, the result will contain paths relative to
54   *root_dir*.
55
56   This function can support :ref:`paths relative to directory descriptors
57   <dir_fd>` with the *dir_fd* parameter.
58
59   .. index::
60      single: **; in glob-style wildcards
61
62   If *recursive* is true, the pattern "``**``" will match any files and zero or
63   more directories, subdirectories and symbolic links to directories. If the
64   pattern is followed by an :data:`os.sep` or :data:`os.altsep` then files will not
65   match.
66
67   .. audit-event:: glob.glob pathname,recursive glob.glob
68   .. audit-event:: glob.glob/2 pathname,recursive,root_dir,dir_fd glob.glob
69
70   .. note::
71      Using the "``**``" pattern in large directory trees may consume
72      an inordinate amount of time.
73
74   .. versionchanged:: 3.5
75      Support for recursive globs using "``**``".
76
77   .. versionchanged:: 3.10
78      Added the *root_dir* and *dir_fd* parameters.
79
80
81.. function:: iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False)
82
83   Return an :term:`iterator` which yields the same values as :func:`glob`
84   without actually storing them all simultaneously.
85
86   .. audit-event:: glob.glob pathname,recursive glob.iglob
87   .. audit-event:: glob.glob/2 pathname,recursive,root_dir,dir_fd glob.iglob
88
89   .. versionchanged:: 3.5
90      Support for recursive globs using "``**``".
91
92   .. versionchanged:: 3.10
93      Added the *root_dir* and *dir_fd* parameters.
94
95
96.. function:: escape(pathname)
97
98   Escape all special characters (``'?'``, ``'*'`` and ``'['``).
99   This is useful if you want to match an arbitrary literal string that may
100   have special characters in it.  Special characters in drive/UNC
101   sharepoints are not escaped, e.g. on Windows
102   ``escape('//?/c:/Quo vadis?.txt')`` returns ``'//?/c:/Quo vadis[?].txt'``.
103
104   .. versionadded:: 3.4
105
106
107For example, consider a directory containing the following files:
108:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub`
109which contains only the file :file:`3.txt`.  :func:`glob` will produce
110the following results.  Notice how any leading components of the path are
111preserved. ::
112
113   >>> import glob
114   >>> glob.glob('./[0-9].*')
115   ['./1.gif', './2.txt']
116   >>> glob.glob('*.gif')
117   ['1.gif', 'card.gif']
118   >>> glob.glob('?.gif')
119   ['1.gif']
120   >>> glob.glob('**/*.txt', recursive=True)
121   ['2.txt', 'sub/3.txt']
122   >>> glob.glob('./**/', recursive=True)
123   ['./', './sub/']
124
125If the directory contains files starting with ``.`` they won't be matched by
126default. For example, consider a directory containing :file:`card.gif` and
127:file:`.card.gif`::
128
129   >>> import glob
130   >>> glob.glob('*.gif')
131   ['card.gif']
132   >>> glob.glob('.c*')
133   ['.card.gif']
134
135.. seealso::
136
137   Module :mod:`fnmatch`
138      Shell-style filename (not path) expansion
139