Build file lists for batch processing
Collect files matching an extension in one directory or a subtree.
Python · Module
glob
The glob module finds filesystem pathnames with shell-style patterns such as *, ?, and []. Use glob() for a list or iglob() for lazy iteration, with optional recursive searching via **.
How it works
The module expands shell-style pathname patterns without invoking a shell. Use glob() when a list is convenient, or iglob() to yield matches lazily; recursive ** traversal and root_dir support searches below a chosen directory.
Syntax
glob.glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)
glob.iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)Parameters
| Name | Type | Description |
|---|---|---|
pathname | str or path-like | Path pattern string containing shell-style wildcards. |
root_dir | path-like or None | Root directory used as the search base when supplied. |
dir_fd | int or None | Directory file descriptor for relative searches. |
recursive | bool | When true, ** recursively matches files, directories, and directory symlinks. |
include_hidden | bool | When true, hidden path segments can be matched by wildcards. |
Returns
glob() returns a possibly empty list of matching path names; iglob() returns an iterator yielding the same values.
Key points
globexpands filesystem path patterns using shell-like matching rather than executing a shell.- Implementation uses directory scanning and filename matching, so it does not invoke a subshell.
iglob()is the streaming counterpart toglob()and is preferable for potentially large result sets.- Matching includes dangling symbolic links, so existence checks may still be needed before opening results.
root_dirchanges the search base while allowing the caller to keep the current working directory unchanged.
Common mistakes
- Do not rely on result ordering; sort the returned paths when deterministic processing is required.
- Patterns do not expand
~; expand a user directory separately before globbing. - Recursive
**can traverse a large tree, so avoid using it without a bounded search root.
Example: Recursively list Python files
from pathlib import Path
import glob
root = Path(".")
for name in glob.iglob("**/*.py", root_dir=root, recursive=True):
print(name)This lazily walks Python files below the current directory and prints relative matches.
When to use it
Stream large search results
Process many matches without retaining the complete result set.
Use a controlled search root
Search a directory tree while preserving the process working directory.
Interview questions
QWhat does glob.glob() return and which patterns does it understand?
glob() returns a possibly empty list of path names matching a string pathname pattern. It supports shell-style *, ?, and bracket character ranges, and includes broken symlinks in its results.
Follow-up: How would you avoid storing every match at once? Use iglob(), which returns an iterator yielding the same values without storing them simultaneously.
QHow do you perform a recursive glob?
Set recursive=True and use ** to match across directories and subdirectories. The recursive pattern can also match symbolic links to directories.
Follow-up: How can the search be rooted elsewhere without changing the process working directory? Pass root_dir; relative results remain relative to that root.
QHow are hidden paths handled?
include_hidden=True allows wildcards to match path segments beginning with a dot. Without it, hidden directories are not matched by the recursive ** pattern.
Follow-up: Does include_hidden=True perform tilde expansion? No; tilde expansion is outside glob's pattern matching and must be handled separately.
Related
glob.globglob.iglobglob.escapeos.scandirfnmatch.fnmatchpathlib.Path.glob