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