fnmatch

Key Features

• Supports four wildcard characters: *, ?, [seq], and [!seq]
• fnmatch() follows platform case rules via os.path.normcase() (case-insensitive on Windows, case-sensitive on Unix)
• fnmatchcase() always performs a case-sensitive match regardless of platform
• filter() efficiently returns all matching names from an iterable, backed by the module-wide compiled-pattern cache that fnmatch(), fnmatchcase(), and filterfalse() also share
• translate() converts a wildcard pattern to an equivalent regular expression string
• Doesn’t treat the path separator / specially, so use glob for full pathname expansion
• Treats leading periods as ordinary characters, so * and ? match dotfiles, unlike glob

Pattern Syntax

To match a literal *, ?, or [, wrap it in brackets: [*], [?], [[].

Frequently Used Classes and Functions

Examples

Demonstrating all four wildcard characters:

>>> import fnmatch

>>> fnmatch.fnmatch("report.txt", "*.txt")
True
>>> fnmatch.fnmatch("data_2024.csv", "data_????.csv")
True
>>> fnmatch.fnmatch("log_a.txt", "log_[abc].txt")
True
>>> fnmatch.fnmatch("log_d.txt", "log_[!abc].txt")
True

Using fnmatchcase() for consistent case-sensitive matching across platforms:

>>> import fnmatch

>>> fnmatch.fnmatchcase("Report.TXT", "*.txt")
False
>>> fnmatch.fnmatchcase("report.txt", "*.txt")
True

Converting a wildcard pattern to a regular expression with translate():

>>> import fnmatch, re

>>> regex = fnmatch.translate("*.txt")
>>> regex
'(?s:.*\\.txt)\\z'
>>> bool(re.match(regex, "report.txt"))
True
>>> bool(re.match(regex, "report.csv"))
False

Common Use Cases

The most common tasks for fnmatch include:

• Filtering lists of filenames returned by os.listdir() or os.scandir()
• Matching filenames against multiple patterns in a loop
• Building tools that accept shell-style wildcard arguments from users
• Converting wildcard rules into regular expressions for more complex matching logic

Real-World Example

The following script uses fnmatch.filter() to sort a list of log filenames into categories:

import fnmatch

log_files = [
    "app_jan01.log",
    "app_jan02.log",
    "err_jan01.log",
    "app_feb01.log",
    "debug.log",
    "access.log",
]

jan_logs = fnmatch.filter(log_files, "app_jan??.log")
err_logs = fnmatch.filter(log_files, "err_*.log")
all_app = fnmatch.filter(log_files, "app_*.log")

print("January logs:", jan_logs)
print("Error logs:", err_logs)
print("All app logs:", all_app)

Run it from the command line:

$ python log_sorter.py
January logs: ['app_jan01.log', 'app_jan02.log']
Error logs: ['err_jan01.log']
All app logs: ['app_jan01.log', 'app_jan02.log', 'app_feb01.log']

The ? wildcard in app_jan??.log matches exactly two characters of any kind in the day-number position, while * in the other patterns matches any sequence of characters.

Related Resources

Tutorial

Python's pathlib Module: Taming the File System

Handle file and folder paths the modern way with Python pathlib, a built-in module whose semantics work the same on every OS.

intermediate python stdlib

For additional information on related topics, take a look at the following resources:

• How to Get a List of All Files in a Directory With Python (Tutorial)
• Listing All Files in a Directory With Python (Course)
• Working With Files in Python (Tutorial)
• Regular Expressions: Regexes in Python (Part 1) (Tutorial)
• Python Command-Line Arguments (Tutorial)
• Using Python's pathlib Module (Course)
• Python's pathlib Module: Taming the File System (Quiz)
• How to Get a List of All Files in a Directory With Python (Quiz)
• Practical Recipes for Working With Files in Python (Course)
• Working With Files in Python (Quiz)
• Regular Expressions and Building Regexes in Python (Course)
• Regular Expressions: Regexes in Python (Part 1) (Quiz)
• Command Line Interfaces in Python (Course)